Welcome to Mahemoff's blog on web development, UX, and software development. I most recently worked in developer relations at Google, focusing on Chrome and HTML5, and am now busy baking a few apps independently.
Follow @mahemoff on Twitter
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.
[...] 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. [...]
[...] (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 [...]