Docs, Docs, Docs!

Why documentation is important and how to acquire it.

Source: GitHub’s 2017 Open Source Survey

Documentation is important. That’s not a controversial statement. And still, quality documentation in Open Source is the exception, not the rule.

Part of this is priorities. A large and warranted emphasis has been put on conduct, responsiveness, and other aspects of the contribution flow maintainers are responsible for in each contribution. Because these aspects of the contribution experience rest solely on maintainers, and maintainers presumably already have the skills to improve them, we’ve seen advances in many projects.

This focus on the maintainer’s role in individual contributions seems to have crowded out, or at least put on the back burner, the need for popular projects to prioritize good documentation over other goals.

A recent study by Radboud University Nijmegen in the Netherlands attempts to quantify every step in the flow of a Pull Request. This study goes beyond steps visible on GithHub, it also catalogs the steps both contributors and maintainers take themselves in private, like runnings tests and checking documentation.

Source: Work Practices and Challenges in Pull-Based Development

At each step in the contribution flow contributors check their own code quality. But check it against what?

A new contributor has no understanding of project standards and code style if not well documented and discoverable.

It should be no surprise that GitHub’s 2017 Open Source Survey found that incomplete and confusing documentation is the number one problem encountered in open source.

To users, quality documentation is even more important than it is to contributors, and projects have an order of magnitude more users than contributors.

The key challenge in creating good documentation is that it requires a skillset most open source maintainers do not already have. Looking at a project you maintain from the perspective of a new user or contributor can be difficult if not impossible. In fact, the creator of a project may be the single worst person to author end-user documentation for that project.

The good news is that documentation is something many new contributors can do, and will probably write in a what is more accessible to new-comers than if it were written by a maintainer.

It’s also not prohibitively expensive to pay for professional documentation, depending on the size of the project. With more projects every month raising money on OpenCollective without always knowing what to spend it on, professional documentation writing or even editing is a good spend since it’s the number one thing contributors value.

Here’s a list of professional writers and services that have experience in Open Source and are available to contract.

If you have experience with any other contract open source doc writers please reply to this tweet 😘