Documentation as an Open Source Practice

Lisa Tagliaferri

Posted: October 18, 2018•4 min read

Community

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!Sign up

As part of Hacktoberfest season, now is a good time to consider the ways in which we can make open source repositories welcoming spaces for developers and end users alike. A great way to facilitate contributions and grow a user base is through providing documentation and encouraging enhancements to your docs throughout the development cycle.

When thinking about documentation, work to incorporate it as a fundamental part of your open source practice: commit documentation early and often.

Develop Documentation Like Code

Along with your collaborators, document a feature prior to coding it, and document your code as you go along. This will make the codebase more coherent to developers who may work on your project down the line, as well as your future self!

Be deliberate in the documentation you include within programming files and don’t overdo it. Code that is readable and follows a relevant style guide can often speak for itself with some comments along the way to provide context or explain a method that is not obvious. If you add too much documentation within a programming file, it may ironically make the code harder to read. Treat code like it will be read by other humans (because it will be) and comment conscientiously.

Just like everything else in your software project, docs need to be tested and maintained. When you modify code, get in the habit of editing comments and related documentation. Continue to iterate docs along with everything else, mitigating the need to do a documentation push as you approach a release.

Include Community-Focused Documentation

When you are ready to share software with the wider world through an open source repository, be sure to make your project approachable through including key files that provide a description of the software, guidelines and incentives for contributors, and tutorials for developers and end users alike.

Below are the files you’ll want to be sure to include, along with examples of these files from open source repositories available on GitHub.

A README.md file that describes the project and its goals; GitHub initializes this automatically but be sure to flesh it out

The EduBlocks README file is well-organized, with both visual screenshot instructions and manual instructions, and also features contributors in this central location

A CONTRIBUTING.md file to provide instructions for potential contributors — this helps developers understand the best way to collaborate on a project

“Contributing to JupyterLab” provides thorough guidelines and additional resources for contributors

Optionally, you may consider including a CODE_STYLE.md file to give guidance around code best practices to use on a particular project, curl provides a good example

A CODE_OF_CONDUCT.md file with a statement that reflects the project’s community values and sets expectations for both maintainers and contributors

The TensorFlow Code of Conduct, adapted from a few sources including the Contributor Covenant, details standards, responsibilities, and offers guidelines for conflict resolution as well as how to report violations

A CONTRIBUTORS.md or AUTHORS.md file to recognize contributors, which will help you welcome and incentivize community engagement

Calagator offers a typical example of this type of file, with an alphabetical list of contributors and a link to this document from the repo’s README.me file

To support end users, consider including tutorial-style documentation that offers guidance on how to use the software. When writing tutorials, think about who your target audience is, and who your actual audience may be. While you are an expert on your project, approach writing your documentation as though you are a beginner who is using your software for the first time. If you have the resources, consider doing some user testing to watch new users interact with the software so that you can be sure to provide the support that they need to use your software in a meaningful way.

Encourage Documentation Contributions

One of the most important contributions someone can make to an open source repository is a documentation update. For emerging developers, a pull request that improves existing docs based on their experience using a tool provides an entry to get involved in open source. Creating an environment where people are equally acknowledged for code and documentation contributions can go a long way to building a community around your project.

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. Some things you can do to foster engagement include:

Use language that is welcoming and unbiased
Offer natural language translations to better serve distributed communities
Determine the best reading level for your audience
Consider alternatives to text-based tutorials, incorporating audio and visual components may help others understand better
Optimize documentation for screen readers
Ensure that web-based tutorials are A11Y compliant

There are many things you can do to make your project’s docs more inclusive across communities. Welcoming others as collaborators on documentation supports your efforts in meeting the needs of more people so that you can scale your project.

To learn more about technical documentation, the Write the Docs community has comprehensive resources and offers opportunities to connect with others who are working on docs and open source. You can read more about contributing to open source and maintaining repositories by checking out our Introduction to Open Source tutorial series.

Hacktoberfest is on now, and runs until October 31.

Lisa Tagliaferri is on the DigitalOcean Community team. You can find over 2,000 tutorials about DevOps, Development, and Open Source on our Community site. Follow Lisa on Twitter @lisaironcutter.