Victus Spiritus


The secret art of the tutorial

05 Jul 2011

For savvy folks who love learning, there's nothing quite like working through a polished interactive tutorial. Today's riff will focus on the importance of great documentation, and the qualities which separate superior experiences from failed documentation efforts.

In the last couple of years I've crawled through thousands of blog posts, web docs, how to guides, tech reviews, video tutorials, along with a couple dozen technical ebooks1. I simply can't get enough quality documentation on languages, libraries, sdks and frameworks which kick start my enthusiasm and imagination.

I've developed a fine appreciation for well crafted tutorials while delving deeply into the world of modern tech docs. Master crafted guides start small and build up in simple steps, while focusing on the elegance and value of the specific tool under review. Installation and dependencies are boiled down to bare essentials to remove any potential impedance to adoption.

A moment of interruption during a first impression can turn off potential devs or trigger their attention to drift to other sources and technologies. Hackers are short on time, and quick to jump to another solution they can hastily patch together.

One recent example that highlights the advantage of minimized dependencies is my early experience with CoffeeScript. I've found it much easier to dive in with client side CoffeeScript examples which require only a browser and Jeremy Ashkenas' JavaScript interpreter, than to work through server apps which depend on node, several packages, along with databases and interfaces (redis, mongo, couch, etc). I'd love to become intimately familiar with all those layers and plan to dig into cs server apps, but at the beginning they're a distraction.

The critical resource for developers is not discovering sufficient material, but freeing up ample time to work through and understand relevant examples. Competition is fierce in the war to earn mind share from potential partners, and if you want to win it's worth the extra effort spent honing any tech tutorials or documents. Docs are the first and most important surface with which devs contact your technology, whether it's an open source library or an API so make them amazing and keep them up to date.

Common Traits of Polished Tutorials

I've danced about a few of the keys to effective documentation, and now it's time to boil those features down into one definitive hit list:

I could extend this list indefinitely with pet peeves and desired aspects of brilliant tutorials, but this is where reader feedback does a much better job. Please pitch in with documentation features you're enamored with, or mistakes that doc authors keep repeating. I continually strive to make my "how to" posts more fun and effective, and your input helps me achieve that goal.


  1. I grab inexpensive ebooks on topics that I want more cohesive references on. My preferred format is ePub so that I own the file and can read it on my phone, tablet, laptop or desktop. But I have picked up a few texts that are Kindle only. Not all the books I purchase are for cover to cover reading, and unfortunately the references age quickly (ie I upgraded The Rails 2 Way to The Rails 3 Way because it was obsolete in under a year)

  2. Cheap shot on local CouchDB installations. The database and bundled http server depend on building a local Erlang environment and boy does it take a while. The build is only necessary if you're running something customized like GeoCouch. Nifty Mac, Linux, and Windows single server installs are available from Couchbase.