Exemplary documentation: size and purpose

There’s a lot to say about programmer-focused software documentation. It’s more crucial than many developers think, so it is often neglected. Even when its not neglected, it’s often an after-thought. I’ve noticed there are three kinds of documentation I’m interested in.

When I first come across some software, I want short and focused examples of how I can use it for my own purposes. I’m not looking for a lot of theory or exposition; just show me the benefit. If I can’t quickly see how the software works and makes my life easier, I’m very likely to discard it. In other words, I want shorter, “tweet-sized” documentation that sells me on the sizzle right away.

rbenv's README

rbenv‘s old README is a good example. I can see from the screenshot what using rbenv looks like. The bullet points make it easy to know the specifics of what this software is about.

If I come back to some software, I often want to learn the whole thing in one sitting. I want a longer document that I can read through in a serial fashion to learn most or all of the concepts and details about using the code. It should cover the domain ideas of the software, the individual APIs, and how it all works together to make something. To continue the metaphor, I want a well-written, “Instapaper-length” document worthy of reading in a comfy chair.

Backbone.js homepage

The Backbone.js homepage is great at serving as a long-form read. It serves as a reference document and guide at the same time.

After I start using something, I will often want to return to it to remember how to do specific things or to figure out if a task is possible at all. This is when I lean most on traditional API documentation. One to three paragraphs, easily searched are the ideal here. Kind of like the “Tumblr-post” of documentation.

I’ve yet to find all three of these qualities in the documentation for a single piece of software. Finding that software has done a really good job at one of them is delight enough. I can’t imagine how excited the world, at large, would be if something were to have all three. There would be a lot of rejoicing.

Published by Adam Keys

Telling a joke. Typing.

2 replies on “Exemplary documentation: size and purpose”

  1. This actually reminds me of the structure of a Kickstarter project page. At the very top is a video, which gets the point across as quickly as possible. (KS strongly encourages every project to have a video and has numbers to back up the dramatic difference they make.) Under that is a narrative to give more detail on the project, and under that is the FAQ which can be scanned easily to find specific answers to questions. The FAQ answers start out collapsed; they aren’t intended to be read serially.

    Software project documentation might take an analogous form: Short “get right to the awesome” instructions at the top, a longer narrative about the concepts, and then a collapsed appendix with FAQ and API methods.

Comments are closed.