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:
- Start with great technology:
Document products that don't suck. If the library, language, or framework you're documenting is horrible, and you absolutely must document it... - Focus on the good parts:
Douglas Crockford did a fantastic job of highlighting the best aspects of JavaScript, learn from his example by diving into the best aspects of the tech you're reviewing - Start small, build up in steps:
Don't begin with the most complex example you can imagine just because it shows every possible configuration of a given tech. Start small with hello world, and build up by adding one tool at a time. As a tutorial author you're a tour guide. Bring devs along for a magic carpet ride by starting on the ground. A drive by pickup at Mach 1 makes for a messy start - Minimize dependencies:
The less I have to do to begin a tutorial the better, browser based walkthroughs are ideal. You don't have to include you're own c compiler but consider a binary instead of having devs build Erlang from scratch2 - Stylize the experience:
Use large sparse elements, quality fonts, and generous whitespace to separate tutorial steps. Let me chew on precisely what's going on in one example before proceeding into something more complicated. Experienced devs can always fast forward simple steps and white space to jump into the deep end
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.
- 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)
- 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.