How to organize and improve your documentation for your favorite repositories
Today is day 4 of #blogvent, where I’m writing a blog post every day for the month of December. Shoutout to @cassidoo for the idea!
Introduction
One of the things I love about working at GitHub is our hackathons. Every few months we have the opportunity to drop what we currently have going on and focus for a few days on something that we really care about. This is ridiculously cool.
For a recent hackathon I decided I wanted to do something a bit different and focus on documentation; specifically the documentation of an internal app that our team uses a LOT day to day, and that other folks in different parts of the org occasionally need to get running. Documentation was very top of mind, as I had just joined a new team and had been reading a lot of documentation.
During a recent GoTime Podcast, the subject of knowledge management was brought up. It was specifically recommended within the podcast to hire folks that are experts at knowledge management to get information out of engineers and into documentation in an organized fashion to accelerate the engineering team.
There was a debate on the merits of hiring an individual specifically focused on this, however it got me thinking a lot about how knowledge is generated and managed within the context of internal documentation, things like playbooks, ADRs, feature docs, etc.
Background
“Good engineers aren’t born; they’re made. Over the course of their career, engineers make design decisions and subsequently learn from them. As a result, their decision-making almost always improves. In contrast, an organization’s collective decision-making doesn’t always improve. Instead, it rises as engineers learn and degrade as engineers leave. To improve organizations’ decision-making quality, engineering managers should search for ways to capture and leverage past design experience. Therein lies the genesis of Engineering Knowledge Management, which is a strategy to capture explicit and tacit design knowledge for reuse in product development.”
It is clear why there is a benefit to writing down information and decisions that would otherwise live in an engineer’s head, and thus would be gone as soon as that engineer leaves. But just writing down that information isn’t sufficient. It needs to be written down in a way that it can be easy for other members of the team to process and use when they need it.
Thus why I began exploring the idea of content management and organization. There is a lot of information out there on this, and here are some key themes that I came across that are important for knowledge management.
Clarity
Writing simple and easy to understand documentation is best for users. One way of doing so is to make sure that you are using easy to understand language. A recommendation that I consistently see is to use something like Hemingway App to help assess the reading level of what you are writing. Additional recommendations that I found came from the GitHub Docs contribution guide:
- Use plain language. Use common, everyday words, and avoid jargon when possible. Terms that are well known to developers are fine, but don’t assume that the reader knows the details of how GitHub works.
- Use active voice.
Conciseness
From The Elements of Content Strategy, a key component of content is that it is concise. This can also be represented by one of the tenets from The Zen of GitHub:
“Anything added dilutes everything else”.
The more content that is out there, the more difficult it will be for an individual to grapple with the ideas.
Organizing an individual document
Most people don’t read content. They scan it.
Documentation should be structured in a way to make it easy to skim or scan. From this document from the GitHub Docs team on optimizing content for scanning or skimming:
- Use text highlighting such as boldface and hyperlinks to call attention to the most important points. Use text highlighting sparingly. Do not highlight more than 10% of the total text in an article.
- Use formatting elements to separate the content and create space on the page. For example:
- Bulleted lists (with optional run-in subheads)
- Numbered lists
- Alerts
- Tables
- Visuals
- Code blocks and code annotations
Documentation Templates
Using a template can apply consistency to documentation and allow engineers to focus on the important parts: the content. The Good Docs Project has a reference on engineering documentation templates, and was shared with me by @zerowidth. Some key items that should be included in a template include:
- Raw template
- Template guide (how to fill out each section in the template)
- Template theory (empower the author to think like a tech writer)
- Template checklist (confirm you have everything covered)
Here is the markdown version of the documentation template I started using for this effort.
Document Template
|
|
Organizing folders of documents
The subject of knowledge management is hot right now, with a lot of information geared towards organizing an individual’s content through initiatives like Building a Second Brain.
One common recommendation from folks following the permanent knowledge management movement is to organize your notes following the PARA methodology, or “Projects”, “Areas”, “Resources”, and “Archive”. I managed to find one example of an engineering team using that same methodology for their documentation, but it didn’t seem to quite fit shared documents in a way that would be easy to navigate and find what you’re looking for.
After reaching out to the incredibly talented engineers I work with about this, I landed on diataxis. Diataxis is a methodology of dividing documentation into the different sections of “Tutorials”, “How-to guides”, “Reference”, and “Explanation”. This seems a bit more relevant to the group of documents typically collected throughout the lifespan of a repository. Here’s a high-level description of each of these categories:
- Tutorials: Learning-oriented experiences
- Give your learner things to do through which they can learn
- How-to guides: Goal-oriented directions
- Address a specific goal or problem (playbooks probably fit in here)
- Write from the perspective of the user
- Task-oriented, instead of learning-oriented like tutorials
- Reference: Information-oriented technical description
- Reference material is useful when it is consistent
- The structure of the documentation should mirror the structure of the product
- Provide examples
- Explanation: Understanding-oriented discussion
- Deepens and broadens the reader’s understanding of a subject. Reflection is important. Explain why something is done a certain way
Organizing documentation in a group like this allows for managing the collection of documents holistically. It’s a lot easier to see what is there and what is missing when all features are grouped together, or all product types are listed together.
Goals
My goals for the hackathon were to:
- Develop a strategy for managing internal documentation
- Apply it as best as I could within the timeframe allotted
Strategy
Below is the strategy that I used for internal documentation grooming as part of the hackathon, and that I hope to apply to more repositories in the future. If you have ideas on this, I would love to hear them!
- Develop a documentation template (or multiple) that can be applied to the documents within the repository
- Divide the documents into the diataxis folder structure, and add additional sub-folders as necessary
- Do a first pass of each document already in the folder
- Apply the standardized template
- Add a Table of Contents for sections of the document
- Identify where the document belongs in the above folder structure
- Write a standardized document name that matches other documents in the same folder
- Once the documents are in the standardized format, look at the collection of documents and the individual documents more holistically
- Is anything duplicated across multiple documents?
- Is there enough context on why this project exists in the first place?
- Identify any gaps in knowledge and record them to update in the future. Things to think about include:
- Could the document be improved with more images?
- Could the document be more clear with diagrams, like entity-relationship diagrams?
- Is there shared terminology that should be included?
- Could linking to other documents make this document easier to understand?
- Identify each stakeholder that may access these documents and make sure there is a quick path to them finding what they need (stakeholders to think about: internal developers, integrators, product, support) s/o to @sampart for this recommendation
- Write a documentation guide for the repository for future document creation and updating (where doc templates live, how to decide what folder docs go in, etc)
Results
I applied the above strategy to our internal app and saw a lot of great feedback from team members after the hackathon.
But more telling were the comments I got from other individuals months later, as they had to interface with our application and saw my name in the commit history of the docs. Things like “Wow, these look great, and it was so easy to find what I was looking for!”. That was enough for me to realize that the knowledge management efforts were totally worth it.