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.

4 thoughts on Documentation Needs Examples (Duh)

  1. Pingback: ntschutta.com » Blog Archive » Give Me Examples!

  2. Pingback: Man pages that read more like legal contracts

Leave a Reply