I’m constantly amazed at the amount of documentation people are inclined to create without including a single example.
Man pages that devote pages worth of command-line options, flags, grammar, caveats, historical anecdotes, and NOT A SINGLE EXAMPLE.
Textbooks that devote pages to a particular API, then expose it all in one monolithic program.
Countless reference documentation on HTML tags and CSS grammar, and NOT A SINGLE EXAMPLE.
In a world where free videos make it stupidly obvious how to kickstart your lawmowing experience and watching a screencast precedes the creation of “Hello World” in any language you care to adopt, let’s get it straight: An example says a thousand words.
If we’re talking about open source, project source, or your source – I’ll state the obvious: the documentation is the tests. Sadly the state of tests are at least as bad as so-called documentation.
Just remembered I wrote about documenting things a couple years ago.
ntschutta.com » Blog Archive » Give Me Examples! // Sep 25, 2006 at 1:21 am
[...] I just had to second Michael Mahemoff’s recent post about examples in documentation. I really am amazed that examples aren’t more widely used – but I’d sure like to see more of it. It seems so easy…so basic. But then common sense isn’t all that common. [...]
Man pages that read more like legal contracts // Nov 17, 2008 at 7:47 pm
[...] (it’s documentation, not code, so embrace redundancy!), and most importantly, includes an example. (The man page does include examples at the bottom, but (a) they should be included against each [...]