Docs, Docs, Docs!

Why documentation is important and how to acquire it.

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.

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.

• @plaindocs https://www.plaindocs.com is a contract technical writer with open source experience.
• @musegarden http://www.alnelsonwrites.com/ is an open source advocate and freelance technical writer specializing in “documentation that doesn’t suck.”
• @reifyworks https://www.reifyworks.com/ is a consultancy that does developer marketing and can work on messaging and docs.
• @mntnr_io https://maintainer.io/ is a full service open maintainer service that does everything from Issue cleanup to doc writing.
• @jennwrites http://jennwrit.es/ does a bunch of open source community newsletters including Node.js and Hoodie.

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