How to Improve Open Source Software’s Documentation

June 27th, 2012

In my experience, documentation is one of the weakest points of open source software. It's often incomplete, unstructured and/or outdated. There are never enough examples. When examples are present, they often do not follow best practices for the sake of brevity. Another big issue is to distinguish between software versions, as it is seldom clear to what version(s) the current document applies. Digging through the source code should not be seen as a positive user experience.

I have prepared a list of suggestions that open source project leaders can implement to help their users get the most out of their software.

1. Mark Topics as "Incomplete"

Why? When users search for information, they may stumble upon a chapter that deals with their topic. If they do not find the information they came for, how are they to know whether it can be found in another document or whether it was never written?

When authors feel that more details may be useful, but that they do not have time to go in-depth, a note should appear. Example: "the full list of methods for this class is not documented at this time" or "examples for this scenario are not available". There should also be a link to a page that explains the steps allowing users to contribute to the documentation.

2. Allow User Contribution

Why? When users don't find information, they may dig through the source code to understand how to use it. After spending possibly days doing this, the information is fresh in their minds and is of great value to you, the project leader. Allow your users to help you.

You could create a repository with your documentation files and a page on your site that explains how to contribute and what guidelines to follow. Include links to that explanation here and there throughout your docs. Advertise in your network the chapters that need to be completed or ask users to contribute documentation in general.

3. Manage Versions

Why? It is frustrating for users to spend time trying to make something work, only to realize hours later that they were using documentation for the wrong version. Hunting for specific information is hard enough, don't underestimate this effort.

Make the version number of the software obvious in every page. Display links to all versions for which this page is available. Example: "ClassA in version 2.0, 2.1, 2.2". If the currently displayed documentation is not for the latest version, make that fact obvious. Example: "You are viewing version 2.0. The most recent version is 2.2".

4. Structure Information

Why? Users don't know your software like you do, that's why they consult documentation. As such, the table of contents should make sense to the users, who know little or none about your software, not to the author, who knows everything.

There are many ways to structure docs, but allow me to give a few tips based on my most common observations.

Introduction. These often incorrectly assume a level of knowledge that most users do not have. Tools assume that users already used similar tools, that they know what these tools are supposed to do or worse: that users already used a previous version of that same tool. In reality, many users out there only just discovered a new concept. What is MVC? What is Unit Testing? Also, take the time to answer these questions: Who is this software for? What problem does it solve? What problems it does not solve (scope)?

Setup. Dedicate an entire chapter to setup and configuration. Include necessary dependencies and links to their installation and documentation pages. A user must be able to find/access everything in one place and not search online, at the risk of finding the wrong manual and spend hours or more going in the wrong direction.

Quick Start. Show the most basic use of your software. Make sure that you never ignore best practices. Often, documentation show a quick yet wrong way to do something, only to explain pages later how to do it correctly. Should users not get to that last example, you don't want them to "do it wrong" for the rest of their lives.

Self-Contained Examples. Examples should avoid relying on other examples or chapters to make sense. Users don't read the whole manual before they start using software. Once they have a basic understanding, they consult individual pages on a need-to-know basis. When it cannot be avoided, always point users to the related concepts in your docs.

API Reference. For projects where it applies, don't skip the API reference and try to keep it in one location instead of spreading it throughout the manual. Chapters could point to the API reference when appropriate.

A Lot of Examples. Write as many as you can, without repeating yourself. Once again, users don't know your software that well. It may be obvious to you, but it may not make sense to users unless they see it in context. These take a lot of effort, unless you invite your users to contribute.

Please feel free to challenge these ideas and contribute your own in the comments below. I will be updating this post regularly.

Previous: Selenium 2: Wrong Browser Launched Next: Div Higher Than the Image it Contains