Did you know that 72% of developers surveyed by Tidelift in 2019 responded that established policies and documentation was a key decision factor when they were choosing an open source project? And in the GitHub 2017 Open Source Survey, 93% of developers responded that incomplete or outdated documentation was a pervasive problem?
Survey after survey shows that developers care about docs and will pass up working on an open source project or adopting open source technology because it lacks good documentation — even if the project is technically outstanding. The survey results make sense when you consider that many people use a project’s documentation to evaluate how easy it would be to onboard or use the tooling.
So why don’t we have better docs? And whose responsibility is it to create the docs? How do you facilitate contributions and grow a user base while providing and encouraging enhancements to the docs throughout the dev cycle?
The Good Docs Project
There’s a term that’s been kicking around in the open source space known as “docs advocacy.” Defined by Erin McKean, Open Source Program Manager for the Season of Docs at Google, “it’s a developer-focused practice that encourages better software documentationーwhether through creating good docs yourself, helping others produce docs, or by creating a culture that enables good docs to be produced.”
VMware’s Abigail McCarthy, Staff Open Source Technical Communications Manager and Alyssa Rock, Staff Technical Writer, are all for evangelizing docs advocacy. In fact, Alyssa and Erin McKean are both on the project steering committee for The Good Docs Project, an open source community working together to create the templates, tools, and resources to improve the overall quality of documentation in OSS and beyond.
Erin and Alyssa recommend adopting a docs as code (sometimes referred to docs like code) culture in open source to ensure documentation is a major consideration during the development process. Alyssa explains more about how a doc as code culture improves docs advocacy:
In open source, docs as code means treating docs as an integral part of the development process and should be everyone’s responsibility, including developers. In open source, a docs as code culture is especially useful for making documentation scale. Typically in open source you don’t always have dedicated technical writers and often team members wear many different hats. Sometimes you’re coding and sometimes you’re documenting. When you have a docs as code system, it becomes easy for any member of the team to switch between doing documentation work and development work since they all use the same processes and tools. Or even better: you can do those tasks in parallel, meaning you document as you go. That helps ensure that technical writing competencies are spread across your entire team rather than creating a bus factor scenario or a throwing the work over the fence scenario where only 1-2 people do the documentation work and they may lack some of the context for why the work is needed in the first place.
Are Docs Dev-Focused or Tech Writer-Focused?
Alyssa emphasizes that docs advocacy is developer-focused, not necessarily technical writer-focused. The distinction is important because there’s a lot of software in the world that needs documentation and there aren’t enough technical writers to do the documenting. If developers and other non-technical writers can take on some of the easier, lower-order level documentation (such as creating the initial rough drafts of documentation for new features or fixing technical inaccuracies in the documentation), it frees up technical writers’ resources — if you have the luxury of having them in the first place — to work on higher-order documentation tasks (such as information architecture or complex documentation that takes more technical writing expertise to produce).
The million dollar solution?
You can encourage developers and non-technical writers to contribute to the docs by implementing a docs as code system into your project, and in doing so, cultivate a culture that makes producing documentation part of a daily practice.
The Docs as Code Workflow
Docs as code systems are used in both proprietary software development and open source.
Eric Holscher and the Write the Docs community, refer to docs as code as a philosophy in which documentation should be written with the same tools as code. The tools being:
- Issue Trackers
- Version Control (Git)
- Plain Text Markup (Markdown, reStructuredText, Asciidoc)
- Code Reviews
- Automated Tests
Alyssa elaborates on the process, “The documentation is stored alongside code in a code repository and uses the same tooling and processes that are used for code development: version control, CI/CD, issue trackers, kanban boards, using identical processes for documentation reviews that are used for code reviews, etc.”
When development teams implement docs as code, the docs are integrated into the workflow of product teams, and enable a culture where both writers and developers “own the documentation” and work together to make it as good as possible. The approach provides these other benefits:
- Incentivizes developers to think of documentation as being just as important as the code itself, helping to make the work feel a little more approachable and doable.
- Incentivizes developers to write about features when they are top of mind to prevent new features that can be blocked if lacking documentation.
- Integrates writers with development teams better.
Eric Holscher advises that there’s a lot more to building a proper docs as code workflow and refers to this open source tool chain to show how the docs as code approach can be implemented.
A Final Word on Docs Advocacy
Remember, lack of documentation is the top reason developers decide against using an open source project. Docs advocacy, however, provides better documentation practices to developers, the folks who often have the most power to bring about change.
What’s stopping you from beginning your docs as code journey? Why not start today?
A big thanks to Alyssa Rock for her valuable input and whose enthusiasm and love of docs is contagious.
In Part 2 of this blog series, we’ll cover the different types of documentation and solutions they provide, friction logs —one of the easiest and most valuable ways to start making a meaningful contribution to a project right away — and more on Write the Docs and The Good Docs Project, and making beginner-friendly contributions in GitHub.
Resources to Make Docs Easier for Developers
- Organizations that have implemented docs as code systems have seen some amazingly positive and transformative effects. Take a look at these presentations from Google and Twitter’s tech writers at the Write the Docs Conference in 2015 to see their results.
- The Good Docs Project which actively develops documentation templates and other tools and resources for OSS projects that want to improve their docs.
- “Docs for Developers” is a recently published book Alyssa Rock simply raves about as one of the best software documentation books she’s ever read. Pick up a copy!
- The Write the Docs website.
- Google’s free course on technical writing designed to be run by communities of learners.
- The Season of Docs which provides support for open source projects to improve their docs and gives professional tech writers an opportunity to gain experience in open source and github.com/google/opendocs, a repo that contains useful templates for creating software documentation, created by the Cloud iX team at Google.
Stay tuned to the Open Source Blog and follow us on Twitter for more deep dives into the world of open source contributing.
