Sometimes, we get so used to looking at things from a certain perspective that it is getting increasingly harder to see how it may look for others. For instance, no matter how important it is for technical writers to think like readers to deliver better user manuals, it can be a tough call.
Let’s shift our perspective and try to understand how people actually read technical documentation. It will help to get the idea how the docs can be improved.
Where Documentation Can Be Found
Readers do not magically find themselves on the pages of your docs. It can be quite a journey for them to reach the right page. Make sure to add links to technical documentation to all relevant pages. It can be the Resources page, the Customer Care page, the Support Portal — what have you.
The next step is embedding technical documentation in the tool. If we are talking about software documentation, this is essential. Context-sensitive help is a lifesaver for many users. The popups can contain a brief description/explain a feature and a link to the help topic.
Searching for Answers
When a reader finally opens a user manual, in the perfect world, it is the exact help topic they need, they study it and return to the product to apply the newly-gained knowledge. In reality, this might not be the right topic at all, or the reader might need more information. In either case, the search has to work well.
Irrelevant search results inside documentation are a major disappointment for readers. That is why at ClickHelp we are investing so much time in our patented full-text search engine!
Hi! My Name Is
Besides the search, there’s one more thing readers love — the table of contents. However, most of the time, they prefer the search box and the TOC remains a supplementary tool. It has a lot to do with our habit to Google everything (which raises the expectations for search results relevance to the sky — one more reason to consider improving the search), plus, many technical writers struggle with high-level architecture and the TOC’s logic inevitably suffers making it very difficult to find the right topic.
Structure of the TOC needs to be determined on the earliest stages of documentation development. But even if the table of contents is perfectly logical, getting the titles right can turn out to be a bigger challenge. This is another thing demanding your attention.
Help Topic Layout
The readers expect layouts to be similar throughout a user manual. Make consistency a priority for the maintenance process.
Your default layout must be reader-friendly, of course. Meaning that paragraph division and title hierarchy should be in place, as well as additional elements like a mini-TOC in case a help topic gets too long (BTW try avoiding lengthy topics if possible), other navigation elements, information and warning boxes. Don’t forget to add in images, gifs, tables, and schemes to the mix! If readers see a wall of text they will run away.
More Navigation
Readers should not feel restricted inside a help topic. They need to see where to go next. We have briefly mentioned the mini-TOC as a way to simplify navigation within a help topic, but what readers will most likely look for is the way to keep digging into a question or a product area.
Modern software for help writers has many options in this regard. As far as ClickHelp is concerned, we offer breadcrumbs, See Also lists, links to the Top, Next and Previous topics… The learning curve will be so much smoother when you are giving clear directions!
Conclusion
These are high-level things that will help readers find the docs they are looking for faster. With user experience, there’s always a place for improvement. We suggest following readers footsteps to understand what can be done to make the path to their success shorter.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices
Originally published at https://clickhelp.com.
