←back to thread

Examples are the best documentation

(rakhim.exotext.com)
417 points Bogdanp | 1 comments | 09 Oct 25 19:34 UTC | HN request time: 0.201s | source
Show context
bigstrat2003 ◴[10 Oct 25 07:03 UTC] No.45536084[source]▶
Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both.
replies(9): >>45536223 #>>45536396 #>>45536589 #>>45536670 #>>45538529 #>>45539526 #>>45539542 #>>45541440 #>>45542420 #
ux266478 ◴[10 Oct 25 18:52 UTC] No.45542420[source]▶
The state of man pages in the GNU + Linux ecosystem is just atrocious in general. You can thank the GNU Project for that. In sane man pages that actually care about quality, examples are specified where appropriate: https://man.openbsd.org/apropos.1#EXAMPLES
replies(1): >>45547666 #
1. 1718627440 ◴[11 Oct 25 09:00 UTC] No.45547666[source]▶
The GNU project choose to separate documentation into reference (man pages) and tutorials and prose (info). It works quite well and in my opinion info is also superior since it is an interactive hypertext system. So you can have cross-references, outlines, alternatives for different audiences, etc. .