sandal edited this page Dec 14, 2011 · 40 revisions

High quality software tends to be well organized and well documented so that it is easier for users to understand. This understanding helps users to find the right tools at the right time, making them happier and more productive. The Sinatra web framework provides a great example of a software project that has placed a lot of emphasis on understandability, and evidence of this can been seen by simply browsing through its README. From this introductory guide, we can extract some useful patterns for how to write documentation that will make our software more understandable.

1) Start with a "Hello World" example

Like many introductory texts for programmers, the Sinatra README starts with a "Hello World" example that represents the most simple possible program you can build with the framework. While the code itself is utterly boring, a "Hello World" program is an important tool for introducing new users to a project, because it gives them a basic acid test that verifies that they are able to get the software up and running. A "Hello World" example also hints at the minimum amount of complexity the user needs to be comfortable with, and can help steer away those that are looking for higher level tools.

2) Provide a comprehensive overview

While it might be overwhelming to present each and every feature provided by your software in an introductory text, it is a good idea to at least cover all major use cases for the software. All too often README documents only cover a couple of the most common uses for a given tool, hiding much of what it can be used for. Comprehensive introductory documentation makes it easier to indicate to users whether or not a given tool is suitable for their needs.

3) Establish an information hierarchy

While it is important to cover all the key bits of functionality our software provides, some operations will naturally end up being much more common than others. These bits of information should be presented first, so that the user notices them as early as possible in their reading. Additionally, the more complex your software is, the more likely it is that its areas of functionality can be grouped together into different subcategories. Introducing an information hierarchy into your documentation can be helpful, as it will make it easier for the user to drill down into the areas that apply to their task.

When we read the Sinatra README, the prioritization and hierarchical organization easy to see. After the "Hello World" example, the next thing discussed are routes, followed by information on how to serve up static files and execute various kinds of templates. While most users will end up needing more than these features, virtually all Sinatra programs will make use of these particular bits of functionality. It is much less common that a user will want to use Sinatra as a Rack middleware, and so that information is buried much deeper in the README. However, because it can still be found by a quick scan through the sidebar, it is likely that a user who has that particular need will still be able to find the relevant information quickly. These ideas for how to organize information are mostly just common sense, but Sinatra succeeds here where many other projects have fallen short in their documentation habits.

4) Use as many examples as possible

The Sinatra README is absolutely chock full of code examples, with just as much code as written prose. This "don't just tell, show" approach is very valuable for helping users evaluate a project to see if it will meet their needs, and avoids ambiguity that can arise from descriptions that aren't accompanied by code samples. While the Sinatra documentation could possibly be further improved by using less contrived examples wherever it is possible to do so, the fact that you can see the underlying mechanics and syntax for how each feature works gives you a good feel for the library without ever having to build a program with it. Each individual example can serve as a jumping off point for a search through the project's API documentation, a web search, or a question over IRC/email. Rather than talking about concepts in vague abstractions, it then becomes possible to say "I looked at example X where class Y was used to do Z. Is there an easy way to get it to do W as well?". This is a huge win both for the user and the project maintainer.

5) Write to your real audience

Sinatra's README documentation assumes that you're a reasonably experienced web developer that does not need to be provided a basic introduction to HTTP, templating languages, or pretty much any of the underlying concepts that are involved in writing a Sinatra application. While it would be helpful if the document mentioned the intended audience explicitly, a quick skim through the README will make it clear to the user that Sinatra is not a tool that is aimed at meeting the needs of a novice developer. Many projects make the mistake of providing introductory materials which appeal to beginners even though the project itself is not geared up for that kind of user. While well intentioned, this tends to make the documentation less useful to more experienced developers while simultaneously causing beginners to get to a certain point and then hit a brick wall.

When writing documentation, you need to think about what kinds of people will be using your software and then speak to them directly. It may be the case that you are trying to appeal to several audiences at once, and if so, you may want to write different introductions for different use cases. However, in most cases a tool is really built with a particular kind of person in mind but then documentation is added later on to appeal to a broader base. This only works out well if the software itself has been modified to meet the needs of new classes of users, and otherwise can do more harm than good.

The key thing to remember is that making your software more understandable will help your users tell you what they want and don't want, which will help you figure out how to better meet their needs. Writing good documentation is one of many ways to facilitate this sort of feedback loop.

Turn the page if you're taking the linear tour, or feel free to jump around via the sidebar.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.