5 tips for making documentation a priority in open source projects

Documentation is as important as code, so make sure you treat it that way. Here's how.
63 readers like this.
Files in a folder

Open source software is now mainstream; long gone are the days when open source projects attracted developers alone. Nowadays, users across numerous industries are active consumers of open source software, and you can't expect everyone to know how to use the software just by reading the code.

Even for developers (including those with plenty of experience in other open source projects), good documentation serves as a valuable onboarding tool when people join a community. People who are interested in contributing to a project often start by working on documentation to get familiar with the project, the community, and the community workflow.

Common challenges with documentation in open source

Although everyone agrees that documentation is important and needs to be done, some of the ways we do it result in poor quality and lack of consistency across different parts of documentation in the project. For example, when developers are too focused on code, they don't start working on documentation until the last minute (e.g., right before the release). And all too often, documentation tasks are done by volunteers, people who have a hard time saying "no." To make things worse, people may forget about the documentation after the release, so they never change or improve it, and the vicious cycle repeats.

5 best practices

We have been involved in documentation in a number of open source projects at Linux Foundation Networking and GitLab over the past few years. Below, we're sharing some things we've learned that we hope will help make documentation a first-class citizen in your open source project.

  1. Value contributions to documentation just as much as code contributions: A lot of the focus in many open source communities tends to be on code. One easy way to make sure documentation contributions are valued by everyone is to give equal credit to documentation and code in your community metrics. It should not matter whether a commit, merge request, or pull request is for code or documentation. In addition, when you do community recognition, include key accomplishments by the people who contribute to documentation.

  2. Put documentation and code in the same project repo: We highly recommend that a project's code and documentation both reside in the same repository. (A good way is to make /doc or /docs a top-level directory in the repository.) For one, this makes documentation easy for anyone to find. More importantly, your documentation will be on equal footing as code and other project resources when everything is in the same repository.

  3. Make documentation a requirement for a merge or release milestone: If your project has a lengthy release cycle (e.g., three to six months or more), we highly recommend having interim checkpoints for documentation (like this example from the ONAP community). This ensures documentation work is not put off until right before the release, and instead, everyone works on documentation throughout the release cycle. If it's feasible for your community, you could make documentation a required step for all code contributions that will impact users (see this example from GitLab).

  4. Have a consistent contribution process for code and documentation: We also recommend having a consistent contribution process and using the same toolchains for code and documentation. As we noted earlier, many new community members start contributing by working on documentation, as you often don't need deep technical knowledge of the software to get started. It's good for new contributors to onboard in the community by getting familiar with the contribution workflow and meeting other community members. If these new contributors later want to get involved in other parts of the project (including code), you want the toolchains and contribution process to be familiar. Otherwise, they will need to go through another onboarding process, which creates an unnecessary hurdle for contributors. If your code and documentation have different contribution processes, you may risk creating an impression that documentation is less than a first-class citizen compared to code.

  5. Have well-documented processes for contributing to documentation: This may seem obvious, but it's easy to neglect. Since documentation is a good entry point for new contributors, you want to lower the barrier to entry as much as possible. Having good documentation on the contribution workflow, how to get started, where to find issues to work on, how to get help, and more will go a long way to helping new contributors feel welcome and get involved in your community.

What else?

Do you have other tips for making documentation a first-class citizen in open source communities? If so, please share them in the comments.


This article is based on Ensuring that documentation Is a first-class citizen in open source projects presented at Open Source Summit North America in June 2020. 

What to read next
User profile image.
Ray is a Community Manager at PingCAP where he is helping to grow the TiDB community. Prior to PingCAP, Ray managed open source communities at Cube Dev, GitLab and the Linux Foundation. He has over 15 years of experience in the high-tech industry in roles ranging from software engineer, product manager, program manager, and team lead at companies such as EDS, Intel, and Medallia.
User profile image.
As part of the Ericsson Software Technology (EST) organization, Sofia is involved in driving open source engagements, supporting in establishing the EST business and act as an advocate for open source throughout Ericsson. She is the technical lead for documentation within Linux Foundation Networking and Community Manager for Nordix Foundation.

4 Comments

I think it's important if not essential to have good communications between developers and those writing documentation. For one thing, this is the best way for documenters to keep up with new features, or perhaps old features that now work in a different way. In addition, the documenters can give feedback about something that doesn't work as designed, or could work more efficiently with a little change in code. So it's a two-way street.

Definitely agree. This is another reason why documentation work should NOT be siloed from development activities.

In reply to by Greg P

This is so true and yet so many projects really neglect documentation.

'We have this great API' - That's wonderful but it would be good if we could know how to use it without hunting through the code!

Really wonderful to come across this article, Sofia and Ray. I agree completely. I appreciate that you identify the nuances of making contributing easy as possible and consistent. Also, valuing documentation contributions as equal to code.

I suggest adding that sponsors critique the underlying platform and information design of the documentation from the perspective of personas. That is an unlikely process for typical contributors to do, but possibly very eye-opening.

Sponsors need to be clear eyed about what contributors are equipped to do and what gaps are left.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.