Geeks With Blogs
Liam McLennan

Posts like my intro to jQuery client-side templates may appear, at first glance, to add nothing to the existing body of knowledge. However, the trouble that I regularly encounter with technical documentation is that the author tries too hard to be exhaustive. When first approaching a new topic the reader is most interested in the success scenario. Under normal conditions, how would I use this technology? What is the most basic syntax?

A great example of documentation that focuses on the core usage of a technology is Joel Spolsky’s excellent Hg Init. The top level topics are: Subversion Re-education, Ground up Mercurial, Setting up for a Team, Fixing Goofs, Merging and Repository Architecture. These are exactly the things I want to know about as a Hg newbie.

Much as we describe software functionality with user stories, the best introductory documentation is grouped by ‘what is the reader trying to do’, instead of alphabetical or chronological groupings. Once the reader has a working knowledge of the topic then exhaustive reference documentation becomes useful.

Posted on Wednesday, March 3, 2010 7:08 PM | Back to top

Copyright © Liam McLennan | Powered by: