How to Make Your Documentation Suck Less
If you provide a library or service, your documentation is probably the most import resource you have. That’s because it’s what your users will use to integrate with your solution.
Therefore is it imperative that your documentation is as good as it can be! But how do you create good documentation?
The following ideas are some that I’ve found useful when working with documentation.
Someone should be responsible
A camel is a horse designed by a committee
There should be a person or a clear directive that dictates how the content and layout of the page should be structured. The directive or person can then guide the development of the documentation to make sure it doesn’t go out of hand because of multiple individual contributors who try to shape it after their desire.
This is especially important when it comes to the navigation, language use and layout of each page.
Documentation should be part of development
When adding a new feature to your project, you shouldn’t just focus on the code but also the documentation. There should probably be a new section for the added feature and there might also be sections that are obsolete now. There might be sections that needs to be updated to add information regarding the new feature and what it replaced.
I personally try to supply an pull/merge request to the person in charge of the documentation which then can be refined and fixed in terms of language and structure. An added benefit of this approach is that you get to see your code from a new perspective, one of a user which might make you re-think some choices.
Don’t let documentation become a second class citizen, an afterthought.
Revisit the documentation from time to time
It’s easy to get lost in your own writing, so it’s a good idea to get a second pair of eyes on the changes to make sure it makes sense. Even if you did get a second pair of eyes on it, some things might slip through and that’s when it’s good to revisit what was written. Maybe there are things that can be written in a clearer way, or maybe something is obsolete now. How often you revisit depends on how large your documentation is.
No documentation is better than incorrect documentation!
Who are you targetting?
Who is going to read which part of the documentation? If a page has an integration guide it’s probably not a good idea to include information on why your product stands out from your competitiors. That’s something that probably should be on a landing page or sales page.
Make sure to target your message to the persona you expect to visit the page and don’t just dump information. This ties back to having an overall plan of how your documentation should be structured.
Language use and style
The language used in your documentation should be as simple as possible, avoid advanced words such as superflous unless you have to. The person reading your documentation is already trying to understand what you’re providing and the concepts that exists, they shouldn’t be faced with yet another challenge.
Write out acronyms in your documentation when the concept it refers to is explained and later on it could be a link to the explanation or a little tooltip that pops up if you hover over the text.
Don’t insist on saying how easy or simple something is, because it might not be for whomever is reading your documentation. They don’t have access to all the insider information that isn’t documented and the context that you might have build up over years.
Structured layout of pages
The pages in your documentation should contain standard HTML elements such as h1, h2, and p instead of relying on divs with style. The elements should be styled in a such a way that skimming is easy for the reader, and important concepts or words are highlighted.
By using standard html elements, you improve your SEO since it becomes easier for the search engines to understand as well as making your site more accessibility. It’s a win win!
Control your URLs
If your documentation contains example URLs, make sure that you own the domain name or use an domain name that is meant for documentation e.g. example.com. Example.com/net/org/edu are reserved names meant for documentation purposes.
This way you can avoid your users from clicking a link that points to a bad actor ( it was up for grabs after all).
References
If you want to dig deeper into these concepts, I recommend these articles. They contain some really good pieces of information.
- https://google.github.io/styleguide/docguide/best_practices.html
- https://thenewstack.io/an-engineers-best-tips-for-writing-documentation-devs-love/
- https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML
