Software

The not-so-hidden benefits of open sourcing your documentation

Open source isn't just a code thing, and it may well be the best way to ensure your software's users are well-equipped to make sense of your code.

Most people think of open source in terms of code, but one of the more interesting applications of the development methodology is documentation. You know, that thing that makes all that glorious code usable by mere mortals; the thing that makes open source, in other words, truly open.

It's telling, therefore, that one of the top-10 most popular open source projects among GitHub's 96 million repositories is Azure Docs. It would be tempting to view this as a cynical form of open source sharecropping, a way for a "multi-billion dollar business [to] spread the load of maintaining docs." But this overlooks the reality that users of one's software are often the best people to update those docs, and have a sincere interest in doing so.

No docs, no code

While it's rare to find developers who enjoy writing good documentation as much as they like writing good code, there are sound reasons for making above-average documentation mandatory for software, open source or proprietary. As Adrian Ababei has written, the benefits of great documentation include:

  • Your code becomes more understandable and reusable
  • More developers will want to contribute to your project's growth
  • Total beginners (e.g. designers who want to understand the codebase) will feel more empowered to use your software
  • Your project will become more credible, building its reputation on GitHub
SEE: Software licensing policy (Tech Pro Research)

In short, if you want people to use your software, you'd better document it. It won't matter how great the code is if people can't find the "on" button.

As in many other areas, open source developers have led the way in improving how documentation gets written. As outlined by Shaun McCance, developers increasingly use Git for version control, while writing in lightweight languages. At Adobe (where I work) we are standardizing on Markdown as both developers and non-technical product or marketing folks can easily grok it. Other tools or principles like static site generators and continuous integration round out the trends, each making it easier to publish great documentation.

But getting to "great" brings us back to open source itself.

Opening up your docs

Writing on the Digital Ocean blog, Lisa Tagliaferri has highlighted a key reason for opening up one's docs:

It can be challenging for people who are close to the code to fully understand the needs of new contributors or end users. By encouraging the contributions of diverse voices to your documentation, your project will in turn become more useful for more people, positioning it to reach a wider audience. Striving to make documentation inclusive and accessible and seeking out the perspectives of others can also support bringing more developers and end users to your software.

SEE: IT Hiring Kit: Programmer (Tech Pro Research)

Related to this, no development team can anticipate the diverse ways software will get used in projection. Opening the door to user contributions thereby enables users to lend their expertise to the software, fleshing out details in the docs that would otherwise go missing if left to the experience of the original development team.

In my experience, these users—be they novice or expert with the software in question—appreciate the chance to share what they know with their peers and the company or community developing the code. They don't feel abused by the process. They feel ownership.

Which is, of course, another great reason to open source your docs: A more committed community.

Also see

developers.jpg
Image: iStockphoto/SolisImages

About Matt Asay

Matt Asay is a veteran technology columnist who has written for CNET, ReadWrite, and other tech media. Asay has also held a variety of executive roles with leading mobile and big data software companies.

Editor's Picks

Free Newsletters, In your Inbox