Free software is suffering because coders don’t know how to write documentation

GitHub just published its 2017 Open Source Survey. The popular social coding service surveyed over 5,500 members of its community, from over 3,800 projects on github.com. It also spoke to 500 coders working on projects from outside the GitHub ecosystem.

The Open Source Survey asked a broad array of questions. One that caught my eye was about problems people encounter when working with, or contributing to, open source projects. An incredible 93 percent of people reported being frustrated with “incomplete or confusing documentation”.

That’s hardly a surprise. There are a lot of projects on Github with the sparsest of descriptions, and scant instruction on how to use them. If you aren’t clever enough to figure it out for yourself, tough.

Documentation is vital

That’s unfortunate. People don’t quite realize how vital documentation is to the success of a project.

Mike Pope, a well-respected technical writer, once summed up the need for documentation thusly:

We’ve been known to tell a developer “If it isn’t documented, it doesn’t exist.” Not only does it have to be doc’d, but it was to be explained and taught and demonstrated. Do that, and people will be excited — not about your documentation, but about your product.

I came across another brilliant quote about documentation from Stack Overflow founder Jeff Attwood’s blog, this time by JavaScript developer Nicholas Zakas.

Lack of documentation. No matter how wonderful your library is and how intelligent its design, if you’re the only one who understands it, it doesn’t do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.

But beyond the practical reasons for documentation, there’s also the argument that it builds a sense of community. Not only do you know who your fellow collaborators are, and what they’ve accomplished, there’s also a clearly-defined sense of mission and purpose.

Here’s how the Open Source Survey explained it (emphasis theirs):

Documentation helps create inclusive communities. Documentation that clearly explains a project’s processes, such as contributing guides and codes of conduct, is valued more by groups that are underrepresented in open source, like women.

… and documentation is hard, and that’s okay

According to the Github Open Source Survey, 60 percent of contributors rarely or never contribute to documentation. And that’s fine.

Documenting software is extremely difficult. People go to university to learn to become technical writers, spending thousands of dollars, and several years of their life. It’s not really reasonable to expect every developer to know how to do it, and do it well.

And then there’s the fact that twenty-five percent of open source contributors say they read and write English less than “very well.”

But there’s a golden opportunity here. I’d love to see the thought leaders in the industry — Google and Github, if I have to point a finger — step up.

Google just launched a free online course, trying to tempt language experts to become localizers. Why can’t it do the same for writers, in order to teach them the skills required to write about software?

Similarly, GitHub could launch a course aimed at introducing writers with no previous software development experience to Git.

Not only would this help solve the documentation drought, but it would also be a loud demonstration that you don’t have to be a developer to contribute to open source.