Introduction
A documentation can be the key differentiator for a company to succeed. For instance, the online payment solution Stripe is well known among its users for a top of the art doc and it contributed tremendously to its early growth and retention.
But if you are here, probably you don't need more convincing, so let's dig right into our 7 tips for writing better documentation.
Tips
Giving examples
Remember school? Sometimes you would not make any sense of a definition, but given a real case scenario, you will instantly understand.
Concepts in a documentation work the same. It's good to lay out the theoretical part, but it's as important to include real examples.
Exhaustivity 📚
Most users won't read your documentation like they do a novel or a blog article. At Notice, 87% of users don't read a full article*, they are looking for a precise information and will use the navigation, search bar and article internal structure to find that.
The take away? Your users don't care if your articles are very long, they will if an information is missing and they need to contact you. Don't be scared to be exhaustive, cover all the cases and little quirks.
A good search engine 🔎
Talking about search? A whopping 42% of users use the search bar on each visit. A good search engine shall tolerate improperly written queries, synonyms, and report you searches that didn't find any result so you can fill the voids.
Regular updates
A documentation is a living organism, take good care of it. It shall reflect the latest changes in your product/service and the assets shall be up to date (videos, images, links, ...).
A collaborative documentation can help to improve content freshness.
Letting the experts talk
Each member of a team that is dedicated to one topic shall handle their part of the documentation, or at least review content that is dedicated to their specialty.
It's also a good way to give ownership and empower the authors. Giving responsibility for the content and relevance to specific people will improve articles overall quality.
Use images and videos
The foundations of an article shall always be its text content. Because text is indexable, editable, and searchable. However, adding videos and images make your content more entertaining and easier to connect with for the reader.
It's often a good idea to make a video of a long tutorial for example.
Use the right tools
At Notice, our goal is to provide the best tools to do just that, don't hesitate to try it out here.
*only accounting for articles that contain more than 5 paragraphs.
