We all know the value of excellent documentation, but most of us still struggle to write it well.
Poorly written documentation is like food that tastes bad or that’s hard to eat. The sole purpose of documentation is to be read, so it must be well organized and optimized to be easily read and understood.
Whether you’re writing documentation for your product’s knowledge base to help customers or for your company’s internal knowledge management program to help employees this post is for you. Here are the 5 keys to write awesome documentation excerpted from Elements Of Writing Good Documentation, which focuses on code documentation, by Enrico Sacchetti.
1) Be Inviting
The introduction helps uses understand the context and get acquainted. For some users, the documentation will be their first experience with your product.
Consider these things for the introduction:
- Who’s using it?
- Why are they using it?
- What are they using it for?
- What value does it deliver?
- How does it fit into their workflow?
- Do not overly rely on prior knowledge.
- Keep it short and to the point.
2) Be Succinct
Your goal should be to get users to a basic understanding in under an hour.
Assume your readers are impatient, short on time, inexperienced AND very experienced. How do we satisfy both types of users? Make one obvious easy path for the inexperienced and multiple (more complex) paths for users with advanced needs.
3) Use Examples
The more complex the topic the more examples help. Use your judgement, but good guideline is that if you find yourself getting too detailed then add an example. Vary the examples if there are multiple scenarios.
4) Make Your Work Self-Documenting
This is often more applicable to writing code and working on open source projects, but the lesson is universal: make it easy for those who come after you and pickup where you left off.
As you progress up the ranks this will make it easier to train the new employees you manage or help someone cover for you if you’re out sick or on vacation.
5) Maintain Your Documentation
The documentation for your knowledge base is part of your product. The documentation for your company knowledge management program is part of your work environment. They must be maintained.
Maintaining documentation is a habit, so try to work it into your regular battle rhythm.
Closing Thoughts
The article this post is based on, Elements Of Writing Good Documentation, is focused on documenting code and software projects, but the tips are largely applicable to any kind of documentation. A closing quote from the article:
Almost like art, where inspiration begets its piece, the software begets its documentation. Everyone has different expectations and needs… It’s always tough to please everyone, so all you can do is be critical, accept feedback, follow good elements along with your instincts, and try making documentation that you would love to read.
Originally published at EasyDocs.
