This blog post was adapted from the talk "Using Content Strategy to Improve OSS Documentation".
In 2017, GitHub released the results of its open source survey and found that “developers consider documentation to be highly valuable, but often an overlooked component of the open source ecosystem.”
93% of respondents said "that incomplete and outdated documentation is the biggest problem they encounter in open source projects". That's a staggering find, considering how increasingly vital open source software is to many of the systems and services developers build and maintain every day. But while those of us in the open source community agree that our documentation can improve, we aren't doing enough to move the needle forward.
In fact, 60% of respondents in the GitHub survey said they “rarely, or never contribute to documentation”. And that's a shame, because respondents also believe that “documentation helps create inclusive communities, and clear documentation around a project’s processes are valued by groups that are traditionally underrepresented in open source.” In short, good documentation is important from a usability standpoint, and also, from a diversity and inclusion standpoint.
But while we could draw the conclusion that developers are just not interested in writing good docs, I think the root problem is actually that most developers don't know how. Writing docs is actually hard, and that alone presents an obstacle for many. There's also a lot of confusion around what we mean exactly by documentation and what purposes does documentation serve (aside from simply showing developers how to do something with software). And finally, knowledge sharing as it pertains to documentation needs to improve.
These are all things those of us who are project maintainers need to take time to figure out, because documentation exists to serve users; without it, our software is unusable. It's likely one of the first touch points users will have when they come across your software, and they'll need it to help them understand what the software does, how it'll help them solve their problems, and ultimately, how to start using it.
Content Strategy & Documentation
How we think about documentation affects how much importance we give to the time it takes to develop good documentation. I find it helpful to look at documentation as an asset, something of high-value that we deliver to users in addition to our software. Looking at it as an asset helps us prioritize it properly, and helps us move away from looking at it as an activity that takes place after all of the work on the software is done (in other words, right before launch), to treating it as an integral part of the development process. That means we have to plan for the creation, delivery, and maintenance of this asset, not all that different from the considerations we make toward our software features. As far as documentation, I find that content strategy provides great guidelines to make this easier for us to do.
Content strategy, as defined by content strategist Kristina Halvorson, is the “planning for the creation, delivery, and governance of useful, usable content”. The key word here is plan. To improve a user's experience with our docs, we must move away from starting the writing process at the end (right before launch), to having it happen in parallel to the actual software development process.
Back to documentation. Many of the docs we typically see in OSS fall into one of two buckets:
Project/process related documentation. These docs answer the question: “What is this project?” and also, “How can I contribute to it?” This includes a project description, contribution guidelines, issue reporting guidelines, and things like Codes of Conduct, project license information, information about authors, etc.
User documentation. These docs help the user answer the question, "How do I use this?" and also "What can I do with this?" They include detailed installation instructions, man pages, step-by-step tutorials, guides and/or articles that explain specific concepts in depth, API documentation, and also release notes and changelogs.
So now that we know what documentation tends to look like in open source, and what content strategy is, how can we use the two to improve our docs? Here are some practical steps you can use to start applying content strategy practices in your documentation.
1. Conduct a content audit. The first step to figuring out what to change, is figuring out what you have to work with. This is especially crucial if you’re on a project that has grown considerably, or if people have cycled on and off your core team, because everyone might not know where everything is. A content audit allows you to analyze all of the content you have (and I'm using content and documentation interchangeably here) in order to determine what changes need to be made to it. At a glance, content audits can help you answer some of the following questions:
What documentation have we already created?
Are users able to find this content?
Do we have duplicates?
Should we keep it or remove it?
When was each page last updated?
Where does the documentation live?
It’s common to put this information into a spreadsheet. If you have an external docs site with many pages, use a free site crawler to index all of your pages and it’ll dump it into a spreadsheet for you (or create a script to do the same thing). But ultimately you want a spreadsheet that has at least the following information:
URL (of each doc page)
Page title (what appears in the browser header when someone lands on your page)
Last updated (if available)
Actions to take on each page:
Leave / Remove / Update / Merge
Priority levels for each page:
High, Medium, Low
Share the spreadsheet with members of your project’s core team, and together, go through each piece of documentation and populate as much of this information as you can. Decide what content gets to stay as is, what needs to be removed, what needs to be updated, and what pieces of content can actually be combined into one. It’s a lot of work upfront, but armed with this information, you can start to prioritize your documentation needs, and you can decide what items can get added to the backlog for contributors to work on. Essentially, an audit is a tool that can help you incrementally manage the process of creating and updating documentation.
2. Host docs on an external site. There are a few benefits to having your docs live outside of a public repo, in addition to just branding. For one, they're much more user-friendly; it's much easier for users to navigate to a specific site section or page, or even search for that content. Secondly, you can integrate a web analytics tool (like Google Analytics) to glean some information about your users, like the pages with the most views, how much traffic your site is getting, and how the main source they come through (search? Twitter? Stack Overflow? Medium? etc). (Use ga-beacon to use Google Analytics from a GitHub README.)
3. Check in with users. If you only talk to users intermittently, talk to them more. Conduct a user survey and pass it around your community, inviting developers that use your tool to give you a richer sense of how they use it. And create channels where users can send you feedback (especially actionable feedback). For example, if users have a specific documentation request, have two maintainers look at the issue and determine whether or not the doc exists, and if not, whether it makes sense to write something around it. Add that item to your backlog for project contributors to work on or for your team to prioritize for future work.
4. Create templates. They save you time and help remove potential roadblocks for contributors who are not as familiar with how you write your documentation. If you and your team have already produced a few guides and articles, and have a sense for flow, how to layout information, and also, what information to include in a doc, document that and turn it into a template that you make accessible. It’ll save YOU time in the future from having to recall this info, but also, will help you onboard new contributors who are not as familiar with your style. (Look at the Gatsby project's style guide for inspiration. It includes a section on how to format articles.)
5. Make contributor guidelines clear, concise, and easy to locate. Link out to your contributor guidelines from a section in the README (if it lives in a different file), and link out to it from your external site's main navigation for better access. Include things like instructions for setting up a development environment for your project, a breakdown of folder structure with links directly to where the docs live in your public repo, and links to any style guides you are using.
BONUS POINTS: Add calls to action on each of your docs pages to encourage users to actively contribute to that particular page. It signals to users that they are actively encouraged to contribute to the docs. (A few projects that do this are VueJS, Webpack, and Bundler.) Lastly, add documentation-related items to your issue trackers and tag them with descriptive labels. For example, perhaps your team has identified a few items that need to be updated in the content audit. Determine which items might be good for contributors to get started on, and add those to your issue trackers with labels that indicate it's for documentation, what type of action is required (an update, new doc needs to be developed, etc), and whether or not it is appropriate for someone new to open source to work on.
6. Don't go at it alone! Seek out open source projects that you, your users, or peers admire and study their documentation. Ask others what it is about these docs that they like, think about what it is you find most effective, and determine which specific things would work for you and your audience. Get folks to do peer reviews of your technical articles before you publish to help you spot typos, offer better word choices, and more importantly, test out your doc to ensure it isn't missing any relevant information.
Finally, make friends with technical communicators. There's an entire group of professionals—technical writers and technical editors—who've studied this and/or do this for a living. There are lots of techcomm-focused conferences that you can add to your conference schedule, techcomm Meetups, and the Write the Docs Slack community.
Resources
Here are additional resources for continued reading:
Creating great READMEs:
Conducting a content audit:
Style guides:
Connecting with writers and technical communicators:
Sources
Here are additional sources I referred to for my talk:
Like this post? Purchase The Developer's Guide to Content Creation for more content-related tips and exercises.