Over 90% of respondents to a recent GitHub survey said that one of the top problems with open source projects is incomplete or confusing documentation.
What can we do to fix it?
GitHub users identified poor documentation as one of the top problems with #opensource projects. How can we fix it?https://t.co/t2Jmt9QDJc pic.twitter.com/d1GEPYT22P
— Alex Sanchez (@_alxsanchez) June 12, 2017
The answer comes in several degrees of intervention.
The first and most obvious is to hire a professional to take care of it. Red Hat is one open source company that has a stable of writers and NPMJS is hiring their first full-time writer. It's safe to say, there are many writers out there working on funded open source projects. This solution is great, and as a technical writer, I am all in favor of it, but it's expensive and difficult.
On the other hand, the lowest degree of intervention is ignoring the problem. Many small open source projects use this method because they don't have the time, energy, money, or expertise to do anything about it. Some at least try to give out stickers for documentation pull requests.
The majority of projects fall into a middle space where there's not enough money to hire a tech writer but they motivated to help users with the product. What can these projects do?
Lower barriers
First, make it easier to contribute by lowering barriers to entry. Here are a few things you can try for little or no money.
- Use templates to guide writing.
- Put documentation in an accessible, open format.
- Allow (and fulfill) feature requests for documentation.
- Capture documentation that isn't attached to your project.
There are dozens of articles and conference talks about enticing coders to become contributors, and everything that is true about code contributors needs is also true about non-code contributors. However, there is a special level of anxiety around contributing documentation that you know people will read, as opposed to code that they may never activate. If you are not a part of the core project team, do you really know enough to document it?
Some projects claim that only experts are qualified to write about the project, and that is false. Anyone can write accurately about a project, just as anyone can write useful code, as long as they have good reviews, sources, and feedback.
Documentation template
Hire a writer or borrow style guides from an existing project to create a documentation template. This is a fillable form that contributors can use to create a meaningful topic or description. For example:
The _______ command tells the system to __________. The ______ command takes the following switches:
_______ sets the file name
_______ turns on logging
_______
Related commands are _____, _______, and ________.
This is a short template, but allowing people to skip the mental overhead of thinking about what they should include really lowers the barrier and makes it easier for them to document as they code, or contribute documentation after the fact. Standardizing the commands this way will also make your project more usable because users can scan them to find predictable information every time.
There are a lot of beautiful, powerful technical writing tools out there. You shouldn't use any of them. You should use something as small and simple as possible to compose and solicit documentation. Ideally, it should be something people can add to with a text editor, and it should be self-compiling so that there isn't a point of failure after the contribution and before publication. Don't put your information into a proprietary wiki: put it into HTML or Markdown, or some other familiar standard. It will be easier to convert it to more professional documentation later.
Documentation requests
Documentation requests should have the same path and weight as feature requests. You need to have a way for people to tell you what it is they’re failing at and ask you for help. If you have a chatbot configured, make sure it is collecting documentation requests. If you have analytics configured, look to see what people are searching for and not finding. Add as many request paths as you can think of, and then you can collate them and do a simple frequency analysis to determine what your users are most frustrated by and work on fixing it.
Any project of sufficient age has documentation that exists somewhere other than the project itself. People are asking each other questions on Stack Overflow, are googling for answers on Youtube, and are asking each other on industry-specific mailing lists. Wherever your users are helping each other, you should also be reading that helpful documentation and pulling it back into the project, with permission. Someone on a library mailing list may never think of coming to your cataloging software to contribute documentation, but they have written it up for their fellow librarians, and it's good useful information.
Making documentation easier means that more people will be creating documentation for you. It's so obvious, but very few projects strive to lower the barrier.
Increase rewards
People change their behavior when they are avoiding pain or seeking rewards. We don't want pain in our projects, so we can work on making rewards a more likely cause of behavior change. Here are some ways:
- Make documentation contributions equal to code contributions.
- Reward requests for documentation (possibly with reviewer duties).
- Outline a contributor progression for non-code contributors.
If you treat documentation and user experience and accessibility as less important than code, it will come through in your project. Make sure you don't have your project separated into "Valuable Coders" and "Those other people, some of whom write documentation." If you give out stickers or T-shirts or challenge coins for code, give them out for non-code contributions as well. For a while, this will be so startling to your community that you'll see a lot of new, excited contributors.
Thank people for asking for documentation. I am especially fond of the idea of giving them a reward for requesting documentation that allows them to review the stuff they requested! Sneaky but effective. Treat it a little like you would a bug report: "There's something making the product unusable for me, and I can’t go forward until you fix it." That something may be a broken feature flag or an outdated installation procedure, but either way, the user is out of luck.
If you have the kind of project that has a progression from user to requester to contributor to core, make sure there is an equivalent path for non-code contributions. If you want someone to volunteer to write you top-notch documentation, you're going to need to show that you value their time and expertise.
Wrapping up
It's not any harder to write code than documentation, it's just a different skill set. As the GitHub survey shows, though, not many people are doing it or doing it well. That's because in general, open source projects have not made usability a priority, whether through documentation or interface.
Changing the problem of bad or missing documentation is both easy, using the steps I outlined above, and very difficult. It will be difficult because it calls for us as a movement to start caring about the experience of people different than us, and that is not something open source has traditionally rewarded us for. There is a culture of in-jokes, old habits, and community hazing that many of us are trying to change. But change is hard, and new users all over the world are getting corrected on how to pronounce the name of an operating system they've only ever read, even if they did manage to install it.
Consider encouraging non-code contributions as your way of making the users that come after you feel less like throwing up their hands and going to commercial software because open source software is too frustrating to use. I know I try to think of it that way.
4 Comments