How do you know if your technical documentation is any good? And, most importantly, how do you fix it if it’s not good enough? Well, there are certain key points that you will need to analyze to make sure your team creates top-shelf user manuals.
We wrote a post on bad and good documentation examples a while ago. Since there's so much data to cover, today, we are going to give you more tips on creating better user manuals and avoiding common mistakes of technical writers.
Poor Product Adoption
Always remember that technical documentation is a sure way of helping to adopt a product. Working in a new environment is always stressful and overwhelming for clients, so let your user manual be their safe haven where all the answers are within reach. Here's what you can do:
Getting Started
Add a Getting Started section. What you should do first is to understand how an average user approaches learning your product so that you could create a Getting Started section based on this data later.
Glossary
Another tip concerning product adoption via technical documentation is creating a glossary. This can be done in the form of a help topic. You can add terms specific to the field in general and your product in particular. All terms should be accompanied by brief definitions. Use links to the corresponding help topics so users can navigate there to get more information about a feature or a process.
F.A.Q.
An F.A.Q. section is a very effective solution to product adoption, as well. To understand what questions should be included, collaborate with the support team. These guys know a thing or two about the frequently asked questions :)
Context Help
To take it a step further, you can create a virtual tour for new users right inside your product using Context Help. We have a thorough description of how Content Help works here.
Basically, the content of help topics is embedded in your product's UI, and users get timely tips in a form of pop-up windows, assistant panels, links, etc. This is a great way to quickly introduce a product to clients! Check out this page for Context Help samples.
Bad Navigation
Lack of proper navigation is what makes most people cringe. What's the point of good content when it is hard to reach? Having a TOC is nice (especially if it is logically structured and intuitive), but it is hardly ever enough. To improve your technical documentation, use the links to cross-reference help topics and take advantage of ready-to-use navigation elements available in help authoring tools.
ClickHelp, our modern technical writing tool, offers a lot in terms of navigation: a TOC, a mini-TOC, breadcrumbs, links to next/previous help topics and more. All these elements can be customized using CSS.
What's even better, we are constantly working on improving this functionality, so, navigation got seriously updated in the recent ClickHelp Aurora Polaris product release.
Lack of Visual Content
If the first thing your client sees when opening the user manual is a wall of text, the chances are they will close this document, repress any memories about this mishap and never ever try reading your documentation again. Visual content is able to simplify even the most complex topics. Always look for the possibility of adding some visuals to text. A gif or a screencast can give as much explanation as a whole page of text in just several seconds. Tables/graphs are must-haves when dealing with numbers or other data that can be structured.
Software documentation requires screenshots. It is a necessity. Just remember that there are certain rules to take screenshots right. Confusing images do more harm, so, do your homework first :)
Here's the link to a curious blog post we made on the greatest technical illustrator in the history of humankind, Leonardo Da Vinci. Turns out, modern technical writers can learn a lot from this famous inventor and scientist.
Conclusion
We know that you have probably seen a lot of bad technical documentation examples in your lifetime. User manuals are complex notions, therefore there are so many ways to ruin them.
The things we have listed in this post are barely scratching the surface of what could go wrong with your technical documents. The devil is always in the details, so, something as simple as lazy spell-checking can spoil the impression once and for all. Feel free to share what common pitfalls of writing user manuals you know in the comment section below.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices