Documentation Best Practices, Part 2: Writing Specific Types of Documentation
This is the second post of a two-part blog series about documentation best practices.
By Nat Hull-Richter
In my first post, I reviewed why we should write documentation and best practices for writing it. In this post, let’s review a few specific types of documentation in more detail.
Not all documentation is created equal. How you write documentation should change based on the type of documentation. Below are some examples of specific types of documentation that should look and feel different from one another. There are likely other types of documentation that I am missing — if you have other types you use and recommend, feel encouraged to reach out or leave a comment below and let me know.
How to guides
Sometimes you need to give other developers instructions for how to build something or solve a particular problem. This type of documentation should be explicit step by step instructions for how to do something. If at all possible, they should include screenshots.
What to include:
- Screenshots of any steps
- CLI outputs
- Links if someone needs to go to a specific page
- Examples of what success looks like
What not to include:
- Unbroken up text
- Anything that is not specifically related to the goal of this how-to guide
Why document this?
TL;DR: These documents exist to make it easy and fast to do what developers need to do.
This type of documentation may seem superfluous. This can be either because it’s possible to find other documentation online about the given topic or because developers should be able to read the code to figure these things out for themselves.
However, it is asking a lot of a developer to force them to figure this out without any guidance. Sometimes it truly is enough to just link out to the related documentation. In these cases, it is still better to link to documentation directly rather than have engineers look for it on their own. While senior engineers should be able to find the documentation and get the information that they want, more junior engineers may have more difficulty.
In other cases, the official documentation is not enough. More senior developers can still find themselves digging through several different pages of documentation to only vaguely find half of what they need. For example, various SAAS (Software-as-a-service) companies will even sell their employee’s time to other companies to help their customers use their product. In each of these cases, they will have official documentation around how to use their products. However, even the company who owns the service knows it’s not enough to get people onboarded to their technology.
Best practices
In general, it’s a good idea to make it easy for developers to know what are the global, organizational and repository specific best practices for an organization. This documentation should be focused on a specific topic and clearly state that topic somewhere close to the top of the documentation.
What to include:
- A clear title, “Goal”, “Why” or “What” statement explaining what best practices are represented in the document.
- Section headers
- Specific examples of:
- The best practice,
- What not to do, and
- How to update the “bad” versions to conform to the best practice
What not to include:
- Anything tangential to the purpose of the document
Why document this?
These documents exist to make it easy to do the right thing. They can serve as helpful learning tools for more junior developers and nice reminders for more senior developers. This is important since best practices can be repository or organization specific in addition to being about the language and framework.
Domain documentation
Domain documentation exists to document a given domain area within an organization. This is really important for maintaining existing domains in addition to handing off these domains to other teams during re-orgs.
What to include:
- A short description of the domain
- Information for how to access the domain in the code
- Information for how to test the domain. This should include:
- Screenshots! and
- CLI outputs! - Links to any important metrics
- Links to playbooks for how to resolve issues related to the domain
- A Q&A or FAQ section for quick debugging
What not to include:
- Anything not related to the domain
- Details that can be moved into a playbook
Why document this?
- The person who writes the code for the domain is often not the person responsible for maintaining it. People change teams and jobs fairly frequently in tech.
- Depending on the size of the company, a given domain can become exceedingly complex.
- Creating documentation while a domain is small will encourage others to build out documentation as they build code
- Once a domain is large, it will become too large to expect any developer to keep in their heads. As developers build more and more features, they will forget important details about an existing domain. - People need to know how to monitor domains to keep them stable. Adding information on how to monitor a given domain to domain documentation serves the double purpose. First, it pushes developers to build tooling to monitor their domains. Second, it gives developers maintaining the domain easy access to this tooling.
There are almost certainly more reasons, but any of the above should be sufficient.
Conclusion
I appreciate everyone who has taken the time to read through both this and my previous post. If you haven’t had a chance to read through my documentation tips and tricks I recommend reading through it here. I hope everyone walks away from this having a deeper understanding of why documentation is needed, why they are writing the specific documentation they do write and how to make that documentation more readable.
