It’s exciting for open projects to grow from a handful of users to a team of collaborators working on and using the software. Moving from one to many contributors is a powerful moment for any project. However, as a project scales and grows, one area is frequently neglected: the documentation.
Missing or insufficient documentation hinders a project’s ability to scale. Most potential users skim your documentation first to see if it fits their needs and to judge how difficult it might be to use. Documentation makes your project’s first impression: not only on potential users, but also on potential contributors.
Writing and improving documentation offers a clear path for people to contribute to your project—provided you offer the right guidance and processes to support them. This article covers best practices for attracting and retaining open-source documentation contributors based on our experience building and managing documentation for Kubernetes.
Evaluate your existing docs
Begin by evaluating your existing documentation. You can’t ask for help from your contributors if you don’t know what you need! As you evaluate your documentation, consider it from the perspective of your users:
- What are my users’ needs? Do these docs meet their needs?
- Are there any features that are undocumented? Is critical information missing? Are there other content gaps to fill?
- What content is outdated and needs to be deleted?
- What content needs to be refactored and clarified?
Don’t get bogged down trying to fix each issue you come across. Instead, open an issue for each problem you encounter.
Once you’ve evaluated your content, review the issues you opened and determine whether you need to fix any issues before you invite contributors to address them. For example, if your documentation consists of a single-page `README.md` file with 2,500 lines, breaking it up into smaller individual documents will lower the barrier for contributors. If your documentation contains outdated content, delete it so that new contributors can join more easily. Fix any issues you think would block new contributors from working on your content.
Triage your doc issues
A simple doc issue triage process might look something like this:
Now that you have a set of issues related to your documentation, apply triage. Triaging documentation issues is similar to triaging code issues: make sure an issue is valid and actionable and assign a priority.
- Validate if the issue is related to your documentation and not related to your code: It’s common for an issue to be related to both. Consider whether new documentation or a code change would help your users more. For example, if a CLI command has a confusing name, you could either document the command better or rename the command to something clearer.
- Assess whether the issue is actionable: Does the issue contain everything a contributor needs in order to fix the problem? Tag unclear issues with something like `needs more information` and follow up with the person who filed the issue. For example, an issue that reads only, “This didn’t work,” without specifying what didn’t work or how to fix it isn’t actionable.
- Assign a priority to the issue: What does the project need to fix first? You can use a priority numbering system (like P0-P4) or specify your priorities with tags like `now`,`next`, and `backlog`.
Finally, for new contributors, tag issues that are quick fixes or good first issues. A label like `good first issue` makes it easy for new contributors to identify issues they can take on when they’re getting started with your project.
Kubernetes uses a doc issue triage process very similar to the one listed above.
Add documentation processes to your contributor guidelines
Hopefully, you already have contributor guidelines (if not, GitHub has great guidance you can follow in setting them out). In your guidelines, include guidance specific to documentation, including:
- How documentation is written and served: Indicate which markup language(s) you’re using, any documentation templates you’re using, and whether you’re using any tools like static site generators to display your content.
- How documentation is organized: Give clear guidance on what types of content belong where, including how files and folders are organized. Specify which kinds of content belong in product documentation and what content might be better suited to Stack Overflow or your project’s blog.
- Any documentation standards: Specify any naming conventions you’re using in your documentation. You can preempt a high volume of questions from your contributors about grammar, capitalization, and punctuation by following a public style guide. Both Google and Microsoft provide public documentation style guides.
- Specific guidance for docs change requests: Provide clear guidance for the contribution process. For example, specify branches on which to open change requests, any tags needed for documentation PRs, and any additional review processes required for documentation.
- Answer contributors’ most common questions: When you find yourself repeatedly answering the same contribution question, add that question (and its answer) to the contribution guide.
For Kubernetes, we created a general documentation contribution guide and guidance for filing a docs PR.
Make it easy (and fun) for your contributors
By providing a clear set of triaged issues and guidelines for contributors to follow, you can scale up your number of contributors. Remember that like code, the processes you’ve created for docs need regular review and maintenance. Review your issues regularly to triage them and remove any that become stale or outdated.
Likewise, set a regular cadence for reviewing documentation PRs. Editdocumentation PRs both for editorial and technical quality and give your contributors timely and friendly feedback.
Finally, recognize the contributors to your documentation. You don’t have to do anything as grand as the open-source peer bonus program. Thanking contributors in their PRs, announcing their names when doing a release, and publicly thanking them for their work on a project’s blog can go a long way to showing your gratitude.
Jared Bhatti and Zachary Sarah Corleissen are Emeritus SIG-Docs Committee members of Kubernetes, and recently co-authored the book Docs for Developers: An Engineer’s Field Guide to Technical Writing.