←back to thread

Examples are the best documentation

(rakhim.exotext.com)
401 points Bogdanp | 3 comments | 09 Oct 25 19:34 UTC | HN request time: 0s | 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 #
1. oneeyedpigeon ◴[10 Oct 25 08:40 UTC] No.45536589[source]▶
I'm always pleasantly surprised that many man pages do have examples. But, sure, they could be a lot more comprehensive.
replies(1): >>45536883 #
2. greenbit ◴[10 Oct 25 09:30 UTC] No.45536883[source]▶
I've developed the habit of checking the end of the page, because that's where the examples are, when there are any.
replies(1): >>45540568 #
3. childintime ◴[10 Oct 25 16:11 UTC] No.45540568[source]▶
PHP documentation stands out with the comment section, like an integrated stack overflow, with examples and gotchas. It's what made PHP great.