Development and UX from Michael Mahemoff. Maker of Player FM. Previously: Google, BT, O'Reilly author.

Menu

Documentation Needs Examples (Duh)

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.

G’Day

Welcome to Michael Mahemoff's blog, soapboxing on software and the web since 2004. I'm presently using HTML5 and the web to make podcasts easier to share, play, and discover at Player FM. I've previously worked at Google and Osmosoft, and built the Ajax Patterns wiki and corresponding book, "Ajax Design Patterns" (O'Reilly 2006).
For avoidance of doubt, I'm not a female, nor ever have been to my knowledge. The title of this blog alludes to English As She Is Spoke, a book so profoundly flawed it reminded me of the maturity of the software industry when this blog began in 2004. I believe the industry has become more sophisticated since then, particularly the importance of UX.
Follow @mahemoff