Yes, please and about documentation for command line programs, also adding example output (not only the command) can help a lot, especially if the reader is unexperienced with the tool.
So much documentation for APIs, CLI programs, _everything_ is painfully lacking in examples.
Or the examples will be just totally wrong or out of date, then search engines and LLMs slurp it up and give you bullshit examples when prompted.
So now a lot of my comments start with `// e.g.`
[0] http://cheat.sh/
Look at the sections in a typical man page:
NAME - Totally useless. I know what the name is, I just typed it in
SYNOPSIS - Explains the syntax and grammar of the command line options in an abstract way [OPTION...] HOST:SRC, and so on. Great if you're deeply studying the tool to learn all the edge cases of running it. Not as helpful if you want to do some specific thing.
DESCRIPTION - Pretty much marketing prose by the man page author. Useless.
OPTONS - Detailed, usually alphabetical(!!) list of each command line options. Great as a reference or if you want to know exactly what action X that known option Y does, but useless the other way around (I want to find the option Y that does known action X).
ENVIRONMENT - Interesting trivia about how the environment affects (or is affected by) the command.
EXAMPLES - THERE WE GO, THIS IS WHAT WE USUALLY WANT.
COMPATIBILITY - Interesting detail if you're on a weird platform or up against the edges of where the command is supported.
SEE ALSO - Useful if you don't even know which command you want.
STANDARDS - Nerd alert! You only care about this if you care what IEEE Std 1003.1-2001 is.
HISTORY - Yawn.
BUGS - Useful to know if it's not doing what you expect.