linuxmemes

I mean, – in college – the running joke in my CS department was to try reading the man page even though it would likely be impenetrable.

I think the issue is that they're written from the perspective of someone in deep knowledge of the entire system already rather than someone who might be using it for the first time and trying to figure out their was around.

Let's take the first fragment of the first sentence of ls's page: "For each operand that names a file of a type other than directory[…]."

Well, what's a directory? Most people use the term folder; that could arguably not be fair as the term directory came first so let's ignore that criticism.

What's an operand in this scenario? While an accurate term, not exactly the most familiar (and certainly not helpful to, say, my partner who, due to dyscalculia, is almost certainly not to be familiar as it's most often used in math). But we crack open a dictionary and find it's the bit manipulated by an operator.

So…the text we give ls? Does that include values we give to the flags (not that I'd know what those are, yet, or what they do). And, of course, the SYNOPSIS describes that text we give as "file" while the very next sentence lets us know that operands can also be directories (mostly, most people think of files and directories as different things) so there's already an overt disconnect between the verbage, description, and examples, disallowing any pattern matching of my brain to quickly piece concepts together.

All of which will probably be hard for me to quickly comprehend as I'm expecting a description of a thing to start with what the thing is rather than immediately describing a small facet of the thing.

Like…I'd argue it's poorly written, on it's own face, but it's utterly bewildering for someone who isn't even entirely certain what all the pieces of the new world they're exploring are, yet, and is trying to piece things together via concept clues.