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.
3 responses so far ↓
1 Rjae Easton // Sep 24, 2006 at 3:04 am
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.
2 Rjae Easton // Sep 24, 2006 at 3:10 am
Just remembered I wrote about documenting things a couple years ago.
3 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. […]
Leave a Comment