Documentation as low hanging fruit

I lean towards the view that “even bad documentation is better than no documentation.” The number of times I find an open-source project I want to use and it has no documentation is unfortunately high. Anyone for whom the complexity of your project is beyond their technical capabilities is likely just to give up and find an alternative.

Good documentation makes your project approachable, and writing documentation is often an easy way for contributors to approach your project. Documentation contributions are often open to engineers of all experience levels and folks in other disciplines and domains adjacent to engineering: product managers, designers, tech writers, QA, etc.

So make contributing to documentation transparent and straightforward.

The bare minimum

Before you start planning growing your project’s documentation, there is a bare minimum you’re going to need to bootstrap your documentation: a README file. A good README looks broadly like this:

• Description of what your project does. A few sentences are optimal. If applicable, a diagram or screen shot is fantastic.
• Instructions for installation.
• Usage, screen shots, and diagrams are fantastic here too.
• Explanation of configuration or API.
• Links to other documentation and references.
• Community and contributing guidelines and direction. Tell people how they can help, for example, by writing documentation and places where they can interact with your community.
• Copyright, contacts, and license.

There are lots of templates and collections of awesome example READMEs that you can crib from too.

Tell the people what you need

Start with creating a series of issues for each documentation element you’d like to generate. Need tutorials? Create an issue in your issue tracker (GitHub and GitLab have trackers, or you can use other tools) for each tutorial laying out the user story for that tutorial.

1
2
3
4
5
6

Installing with Kubernetes

As an engineer, I want to learn how to use AwesomeProject on Kubernetes. 
I want to understand what prerequisites I require, how to install AwesomeProject, 
any required configuration I need to get the project running, how to start it, 
and how to verify it is working.

You can do the same every other element of documentation you require. If you’re unsure what you’ll need, then check out the documentation of open source projects you use that have documentation that engages you.

Give people space

Next, create a rough structure of the project’s documentation using the many tools that statically generate websites. Some documentation-centric examples include:

Docusaurus ReadTheDocs Sphinx

Or you can use any static page generation framework with which you have experience. Most of these tools have templates and theme capabilities that allow you to adopt or adapt an existing design as a shortcut.

You can create a website for your documentation with these tools and then host it. If you use either GitHub or GitLab, they both have Pages products that allow you to host a website for your documentation, or some tools, like ReadTheDocs, incorporate hosting into their solutions.

Map the journey

Map out a table of contents in your statically generated website, using the proposed documentation issues you’ve created as a basis. Create empty template pages for those issues, containing the user story and a link back to the related issue. Now, as each issue is tackled, you’ll be replacing an empty page with the relevant documentation. This also reduces the cognitive overhead for contributors about where to put any new documentation they create but doesn’t preclude them from adding new pages or rearranging the structure.

Edit, merge, deploy, rinse, repeat

Often documentation contributions require less oversight than code contributions; they’re a lot less likely to break your project. They also don’t always need deep knowledge of coding or even the project’s code base. Anyone with experience using the project can provide feedback, edit, or merge documentation submissions. In the vein of “bad docs over no docs,” merging early and iterating is a great way to get a good update tempo going. If an existing document explains something about your project, someone can use that to get started. If they run into problems, fixing the docs is an easy first contribution to your project. One of the advantages of statically generated websites is that regenerating them is easy. This regeneration can be automated using a CI/CD tool, available for free on both GitHub and GitLab.

Making it easy

So know you have the basis for building excellent documentation. Your new README contains contribution guidelines pointing people towards how to help. Your issue tracker contains a list of the documentation you need. You have a structure to insert the documentation into, a framework to generate the website and the means to deploy it. All are making it easier for new community members to contribute to your project.