Mediaboss Marketing

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.

Thats 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 arent clever enough to figure it out for yourself, tough.

Thats unfortunate. People dont 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:

Weve been known to tell a developer If it isnt documented, it doesnt exist. Not only does it have to be docd, 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 Attwoods blog, this time by JavaScript developer Nicholas Zakas.

Lack of documentation. No matter how wonderful your library is and how intelligent its design, if youre the only one who understands it, it doesnt 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, theres also the argument that it builds a sense of community. Not only do you know who your fellow collaborators are, and what theyve accomplished, theres also a clearly-defined sense of mission and purpose.

Heres how the Open Source Survey explained it (emphasis theirs):

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

According to the Github Open Source Survey, 60 percent of contributors rarely or never contribute to documentation.And thats 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. Its not really reasonable to expect every developer to know how to do it, and do it well.

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

But theres a golden opportunity here.Id 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 cant it do the same for writers, in order to teach them the skills required to write about software?

Similarly, GitHub couldlaunch 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 dont have to be a developer to contribute to open source.

Read next: Uber and Lyft are destroying Austin's driver-friendly rideshare economy

Visit link:
Free software is suffering because coders don't know how to write documentation - TNW