How to Improve Open Source Software’s Documentation
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.
These are great guidelines. I’ll be honest, though: the biggest problem is getting people to write documentation in the first place — and, once they do, getting them to be thorough about it. Developers want to write code, not docs.
I can haz solution for that, pretty please? (Seriously — it’s something I’ve been thinking about a lot, and I don’t have an answer yet. Getting devs to write docs is worse than pulling teeth, in my experience.)
Weier O’Phinney, to dig deeper into your problem, I’d say the root cause is lack of education about documentation. For those who attended college, documentation is barely covered, if at all.
When people don’t know what and how to write, docs look like quite a beast to slay. I like to think that most developers, deep down in their hearts, actually want to write it.
I will be presenting about documentation types and how to make it fun at the NorthEast PHP Conference this August. I will post a link to my slides as a follow up to this post.
Another root cause is lack of good integrated tools. When folks can use e.g. Git hooks and have documentation generated upon commits with version numbers and all, then it’s easier to get developers write good docs. See readthedocs.org.
There is a need to strike a balance between thourough documentation/prettiness ans the time people have. I know documentation teams can suck up a lot of time and money and it’s a challenge even for non open source projects. IMO efficient tools like readthedocs that can generate pretty, usable and accessible TTW HTML and PDF docs with little effort other than commenting code or providing external documentation text files (ReST in that case) are a very good first step that even non open source projects could base theirs docs on.
Tools are indeed an important aspect. There are a lot of good tools that leverage the power of version control. It’s not as big an issue as it used to be. Developers should be educated about these tools. Once doc updating mechanism and prettiness are out of the way, the team can actually enjoy writing.
I like to use OpenStreetMap as an example. The contribution tools are easy and fun to use, and so people contribute a lot.
A culture has grown where a problem’s solution may be discussed thoroughly on someone’s blog post–apparently mathematicians like to work this way–and new tools are being developed to allow better interaction. Another aspect is that there is no street cred (read: value) for a good writer vs. a good coder; most employers give writing lip service and remunerate the coders.
phpDocumentor is trying hard to provide tooling that can help with regards to documentation. It is often a very underestimated subject and can provide a lot of value, especially for long-running projects.
My personal experience is that the barrier to write documentation should be as low as possible. Otherwise it could be very easy to ignore that Word document containing the reference, or that Wiki whose wysiwyg editor is a guaranteed head-ache.
One of the latest additions to the phpDocumentor family is ‘Scrybe’ (https://github.com/phpDocumentor/Scrybe); an independent application that can be used to generate documentation from a family of text files following a markup language. It is still in alpha, _very_ young and currently only supports Restructured Text as input format and HTML as output format. But is designed to easily extend to use other formats for both input and output.
Using Scrybe you can literally write documentation fromt he comfort of your IDE and have your Continuous Integration server build the reference documentation for you.
What I am curious to as well is what can be done to make writing reference documentation as easy as possible.
van Riel I’m personally not a big fan of auto-generated documentation. It’s always of higher quality, and makes a lot more sense to the author and reader when written separately.
Regarding tools, I’ve seen teams spend weeks debating them. Once a good one has been chosen, nobody contributed. It’s important, in my opinion, not to focus on tools, but rather on organizational culture and education.
I am not familiar with many tools to simplify reference docs. It would make sense to use one that generates and maintains a skeleton from classes.