Art of Open Source Documentation

A guest post by Jennifer Riggins from eBranding Ninja

Here are some good rules to keep in mind when developing for the open source community.

• Just because you’re offering something for free doesn’t mean you can skimp on it.
• Just because you manage an open source collaborative project doesn’t mean you don’t have to curate it.

Open source documentation is a crucial part of open source management and business models. The home base for most open source projects on the web is undoubtedly GitHub. When GitHub ran their Open Source Survey 2017, they immediately found the biggest complaint was that 93 percent of developers loathed the docs provided. Community is essential to your open source software’s success, and there’s no doubt that documentation is essential to growing and sustaining that community.

Documentation helps your users succeed with your software, empowers them to be self-sufficient, enables them to give further feedback, and is the organizational backbone of your project.

But perhaps the most important reason for open source documentation is that you want people to use your code, right? And to contribute to it, right? WritetheDocs puts it best:

1. If people don’t know why your project exists, they won’t use it.
2. If people can’t figure out how to install your code, they won’t use it.
3. If people can’t figure out how to use your code, they won’t use it.

So, what are you waiting for?

What Makes for Good Open Source Documentation?

The basics are the same as for any form of documentation.

For any piece of code, the main goal of docs is to turn someone shopping around for a solution into an enthusiastic, tell-their-friends user.

This journey begins with outlining the steps to get started, and then code examples to let them know they are on the right track. Here are some things to keep in mind when getting started with writing your open source documentation:

• First, state the goal of your code. It seems simple, but it’s often ignored in docs and is especially important for open source software, which rarely has the marketing budget of proprietary software.
• Be sure to use a lot of hyperlinks to provide more information — this is a great way to keep your docs uncluttered and to define jargony and niche terms. It also allows you to reuse/recycle from other open source documentation, while giving credit where it’s due.
• Don’t forget a hyperlinked table of contents. When many people contribute to the same project, it can become an unwelcoming, organizational nightmare. The open source maintainer acts as a sort of curator, who not only invites everyone to participate, but makes sure there’s a sense of order, common voice, and good user experience. Your docs, starting with the table of contents, facilitates that structure.
• You may also want to consider an open source documentation tool to track revision history. This will help your users understand what has been updated, when. Plus, by releasing updates via the docs to the community, it invites everyone to review quality and do a bit of testing.
• Since you may not have a tech writer dedicated to your project, it also makes sense to use description tools that allow you to automate a lot of the doc writing. This then leaves room for your community to annotate with that personal touch.
• Create a CONTRIBUTING file to communicate with your users how best to collaborate. You could even go so far as creating a docs style guide.
• Finally, while the main purpose of the open source world is not profitability, you should look through your docs for potential to monetize. As you annotate your code and docs, always keep an eye out for pathways for upsells and better marketing. And while docs aren’t blogs, that doesn’t mean you can’t add social media share buttons to create more virality around your open source project.

Don’t Neglect Your Open Source License

This is so important it deserved its own section. Open source isn’t a free-for-all, rather documentation — including documentation of the licensing — clarifies what a user can and cannot do with the code. This can make the license type one of the most important considerations when deciding to use or contribute to an open source project.

Your license will cover who can reproduce the code, who can adapt or modify it, and who can distribute that original or modified code.

If you want your open source project to attract a lot of users, it’s best to apply for one of the most well-known licenses approved by the Open Source Initiative. Mozilla, Apache, MIT, or ReadtheDocs are probably all familiar names to you. Using these well-known and understood licenses can help ensure you are as unambiguous as possible in what people can do with your open source project.

Contributions Start at Home

Additionally, open source documentation isn’t just the responsibility of those curating it. A good way to contribute to an open source project is by contributing to its documentation. In that same GitHub annual survey, they discovered that while incomplete or outdated docs are a huge problem, 60 percent of respondents almost never, or never, contributed to open source documentation.

As stated before, creating a CONTRIBUTING file is a great way to communicate with your users about how best to collaborate. Creating a docs style guide can even help get them to create your docs for you.

After all, writing docs is actually a great way to start getting involved in an open source project. And no matter if you are a beginner user or a master, you can bring perspectives — and fix errors — that will surely improve the docs and the code itself.

Currently based in London, Jennifer tells and markets the stories where tech and culture converge, where the world hopefully changes for the better. You can find her on Twitter or LinkedIn.

DISCLOSURE STATEMENT: These opinions are those of the author. Unless noted otherwise in this post, Capital One is not affiliated with, nor is it endorsed by, any of the companies mentioned. All trademarks and other intellectual property used or displayed are the ownership of their respective owners. This article is © 2018 Capital One.