3 ms·

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 une

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.

scooke 3y ago
This is true... I still often don't know if instructions for entering data should include the "" or the <>...sometimes they seem to, often not. But seeing a screenshot would help.
ReactiveJelly 3y ago
I find myself craving examples for _everything_ even as someone experienced with a variety of tools. 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.`
- PeterisP 3y ago
  I agree that it's the usual case, but on the other hand, right now I got quite frustrated with a project because the manufacturer has only provided examples and tutorials and there is literally no reference material - which was fine when I was starting out, but horrible for debugging where I'd really need just a few sentences describing how exactly that call works and I'd want an exhaustive list of what my other configuration options are there and what they do, not an example of doing something close to but not exactly what I need.
fellerts 3y ago
cheat.sh [0] has been a godsend when the man pages are too dense and I just want to use the tool and move on with my life. [0] http://cheat.sh/ http://cheat.sh/
- ryandrake 3y ago
  I always thought man pages are not only too dense, but they put things in the wrong order. When I look up a man page I'm almost always trying to accomplish some task, so I am looking for instructions on how to do that task. But where are most EXAMPLES sections? At the very end or buried in the middle, if they exist at all! 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.
  - LordShredda 3y ago
    I on the other hand am absolutely grateful for all the 'trivia' they throw in the manpages especially when trying to fix a problem withy system. It's the people that run into edge cases you want to help.

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.

scooke 3y ago

This is true... I still often don't know if instructions for entering data should include the "" or the <>...sometimes they seem to, often not. But seeing a screenshot would help.

ReactiveJelly 3y ago

I find myself craving examples for _everything_ even as someone experienced with a variety of tools. 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.`

PeterisP 3y ago
I agree that it's the usual case, but on the other hand, right now I got quite frustrated with a project because the manufacturer has only provided examples and tutorials and there is literally no reference material - which was fine when I was starting out, but horrible for debugging where I'd really need just a few sentences describing how exactly that call works and I'd want an exhaustive list of what my other configuration options are there and what they do, not an example of doing something close to but not exactly what I need.

fellerts 3y ago

cheat.sh [0] has been a godsend when the man pages are too dense and I just want to use the tool and move on with my life. [0] http://cheat.sh/ http://cheat.sh/

ryandrake 3y ago
I always thought man pages are not only too dense, but they put things in the wrong order. When I look up a man page I'm almost always trying to accomplish some task, so I am looking for instructions on how to do that task. But where are most EXAMPLES sections? At the very end or buried in the middle, if they exist at all! 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.
- LordShredda 3y ago
  I on the other hand am absolutely grateful for all the 'trivia' they throw in the manpages especially when trying to fix a problem withy system. It's the people that run into edge cases you want to help.