Yeah, one big problem of man I found was the severe lack of explanation of what the command is mainly intended to do.
It’s as if the user is expected to run the man after knowing what purpose a specific program exists for, which, I guess is what it is intended for.
I tend to rely on the package manager’s information and other similar sources for that information and man mainly for determining the exact usage.
I don’t at all expect man to be useful for someone who can just follow written instructions.
The reason being than man is just supposed to tell the user, what typy stuff needs to be done for specific functionality. And most programs tend to be doing some small thingy and not fulfilling the user’s whole requirement in one go.
Meaning, to be happy with just man, one needs to be able to create a solution for themselves by properly fitting little parts and that is already more than half way to being able to do programming.
Your man -a intro example and what followed, made me more confused than before of what you were trying to say, so I am just trying to go with the feel of it for now.
Yeah I’m okay with the basic navigation options. The primary point is that man pages do look like they had written by someone who does not do technical writing. Whether that’s someone coming from a law background, programming, or whatever.
It’s not written for an end user who wants to know how to use the tools they have available. It will tell you what a command “does”, sometimes, but it doesn’t explain itself. It presumes a certain amount of pre-existing knowledge, or familiarity with the syntax of man writers.
For another example, the man for ls repeatedly lists options referencing “implied” entries without ever explaining what “implied” means in this context. It presupposes that the reader knows what that term means. I know what an implication is in an English class, and the antonym for “implied” is “explicit”, but in a man page? No clue. Not like there’s reference to or examples of “explicit” entries to contrast with “implied” entries. You just have to know what it means in context, or figure it out some other way.
Yeah, one big problem of
manI found was the severe lack of explanation of what the command is mainly intended to do. It’s as if the user is expected to run themanafter knowing what purpose a specific program exists for, which, I guess is what it is intended for. I tend to rely on the package manager’s information and other similar sources for that information andmanmainly for determining the exact usage.I don’t at all expect
manto be useful for someone who can just follow written instructions.The reason being than
manis just supposed to tell the user, what typy stuff needs to be done for specific functionality. And most programs tend to be doing some small thingy and not fulfilling the user’s whole requirement in one go.Meaning, to be happy with just
man, one needs to be able to create a solution for themselves by properly fitting little parts and that is already more than half way to being able to do programming.Your
man -a introexample and what followed, made me more confused than before of what you were trying to say, so I am just trying to go with the feel of it for now.Yeah I’m okay with the basic navigation options. The primary point is that man pages do look like they had written by someone who does not do technical writing. Whether that’s someone coming from a law background, programming, or whatever.
It’s not written for an end user who wants to know how to use the tools they have available. It will tell you what a command “does”, sometimes, but it doesn’t explain itself. It presumes a certain amount of pre-existing knowledge, or familiarity with the syntax of man writers.
For another example, the man for ls repeatedly lists options referencing “implied” entries without ever explaining what “implied” means in this context. It presupposes that the reader knows what that term means. I know what an implication is in an English class, and the antonym for “implied” is “explicit”, but in a man page? No clue. Not like there’s reference to or examples of “explicit” entries to contrast with “implied” entries. You just have to know what it means in context, or figure it out some other way.