Documentation Best Practices
This is the first post of a two-part blog series about documentation best practices.
By Nat Hull-Richter
Why talk about documentation?
As developers, we are responsible for creating and maintaining code. When it comes to maintaining code and systems, documentation is often a necessity. Since documentation is often a necessity, it’s also important that we think about it in similar amounts to how we think about code.
People may argue that you should “just be able to just read the code” and in an ideal world, code would be self-documenting, but that doesn’t always match up to reality in a lot of cases. Domains shift between teams. The developer who built something is often not the developer who has to debug it. Code gets old and big and messy and digging through it for answers gets tricky (even for the developer who wrote it). Best practices vary from organization to organization. There is no definitive guideline for how to write code. People are constantly thinking about and improving coding practices. There’s lots of resources to dig through to find good answers.
In this two-part blog series, I will review documentation best practices. Part One will look at what we should document, and tips for writing good documentation. Part Two will dive deeper into considerations for specific categories of documentation. My goal is to make documentation less intimidating for developers.
What do we need to document?
Let’s start with what should be documented. In no particular order we can and should have the following documentation:
- How to guides, such as:
- Onboarding docs
- Developer environment setup guides
- Release steps for tricky features
- Playbooks - Best practices documentation, such as:
- Repo contribution guidelines
- Language or Framework specific guidelines - Domain documentation, including:
- Domain repos and setup
- Domain architecture
- How to find the domain in the UI
- How to contribute to the domain
- How to make sure you don’t break that domain
- Playbooks for the domain
- Links to any relevant queries or metrics
Writing documentation
Now that I’ve discussed what types of documentation need to be made, I want to dive into how to create good documentation.
Making documentation readable
Documentation is meant to be read. There is little to no point to writing documentation that people do not read. Below are some basic guidelines that I find valuable for writing documentation.
Make sure you know why you are writing the documentation!
Just because you can write documentation does not mean that you should. The best and easiest to consume documentation is there to answer specific questions. Since I want to make this accessible to others, I will often have a “Goal” section at the top of every document that I write stating what the documentation is for.
Make sure that your documentation includes all and only the necessary information!
While it is fun to info dump and put everything into one place, that is often not as helpful as you might think.
People skim documentation. If there are things they don’t expect in the documentation, they probably won’t notice it.
Similarly, if your documentation is about a particular topic, they will look through it when looking for answers around that topic. When that happens, it can be confusing and frustrating for people who need those answers.
Have sections and section headers for key takeaways
Sometimes people want to read your entire document. Sometimes people are looking for answers around specific things. Having section headers and quick links will make it easier for other people to get what they’re looking for from your documentation.
Keep your documentation short and to the point
Not everyone has 20 minutes to read through a document. Sometimes people want quick answers and don’t want to dig through paragraphs and paragraphs of text. Being precise can help get your point across and makes it more likely people will read everything you wrote.
Add pictures!
If it’s possible to make it easier to use your documentation, using examples or screenshots, do it! This will reduce the likelihood people get lost or confused by your documentation.
Documentation red flags
It’s easy to think that all you need to do is write documentation, but that’s the start not the ending. Just because you wrote the documentation does not mean that it is helpful. While this is not an exhaustive list, here are some signs your documentation isn’t sufficient.
People ask you to explain your documentation.
Documentation is meant to be read not explained. When this does happen, this is an opportunity to get feedback and notes on your documentation.
People miss things explained in the documentation
If people have read or skimmed your documentation and still have issues figuring out how to do what the documentation describes, then your documentation didn’t explain it well.
Possible improvements include:
- Adding pictures to your how-to guides,
- Splitting those things out into separate documentation, or
- Adding section headers specifically for these issues
Common issues with documentation
Even if you don’t have any obvious red flags, here’s some reasons people might have trouble reading your documentation:
- The documentation is too long
- The documentation is mostly about something else
- The documentation is not specific enough
- The documentation is out of date (addressed below)
But who’s maintaining these documents anyway?
Unless your documentation really is autogenerated (like various API docs and dependency maps often are), it’s up to the developers to keep it up to date. Once you create a new feature without documentation or you update your code without updating the documentation, it quickly becomes outdated. Once the documentation is outdated, you find yourself worse off for having wrong documentation than for having none at all.
How to keep things up to date
The simple answer is to make it part of your “Definition of done”. As developers, we can encourage this by:
- Not letting people release code or feature without updating the documentation
- Push for people to document and share out their changes when people create new code or features
End of Part 1
Now that I’ve shared some general techniques, I have a follow up post around best practices for some of the specific types of documentation that I mentioned above.
