What is a perfect help topic? It is a topic that delivers a solution to its readers in the most efficient manner. Creating such topics means paying attention to their every element and analyzing them. Further, you will find practical advice on improving each help topic element to create great technical documentation.
Title
It all starts with a title. A title is a strong position of any text according to linguistics, this means that it stands out for readers, they will notice it and remember it later.
The concept of a title being a strong position is widely used in marketing to catch a reader’s attention. In technical writing, titles are very important, too, although they play a bit different role.
Titles in technical documentation need to be as concise and precise as possible. When looking at your TOC, readers should be able to navigate through it to find what they are looking for effortlessly. So, a help topic title should always reflect the main idea (a feature, a concept, a process, etc.) of the article; and, from our experience, titles with 4 words and longer can’t exactly be called user friendly.
Here’s something about titles most tech writers still find confusing - the usage of capital letters. Did you know, for example, that you should always capitalize the last word of your headline? Or, that some prepositions should be capitalized (like ‘from’) while others shouldn’t? Read this article on title capitalization in user manuals to learn more.
Body
The main principle behind writing a perfect help topic is structuring. The logic behind this is simple - first, you present the main idea and delve on the details later; you write about the cause, and then the effects it has.
Paragraphs are quite important, too; their task is to help readers get the main idea without the need to read each sentence thoroughly. A new point should be presented with each new paragraph. This creates coherence and structure for your help topics.
Screenshots and Images
Most user manuals feature images - sometimes, it is easier to explain things this way. When talking about software documentation, showing parts of UI is a must; without it, users will be totally lost in your software.
There are several things to remember here. The first one is - taking a screenshot is not just a random act of pressing PrintScreen. Poorly taken and placed screenshots can do more harm than good, mislead and cause confusion. Here are some tips on how to avoid this:
- Eliminate all details unimportant for your case.
- Never place two or more screenshots next to each other without any text in between.
- Never let a screenshot/image caption jump to another page.
- Don't let images occupy more than 50% of a page.
To learn more, look through this article on taking screenshots right.
Another important point is finding balance between text and images. We have already mentioned that an image should not occupy more than 50% of a page, but what about a larger scale? How many images should a whole topic contain? To answer these questions, try considering best practices in your field. This way, you can figure out what the target audience can expect and meet their expectations. There are user manuals that consist almost entirely of images while some manage to fulfill their purpose without any. Learn more about balancing text and images in technical documentation here.
Navigation
In thе era of online technical documentation, we should try to get all the benefits from the ‘online’ part.
The obvious advantage of storing user manuals online is the possibility of adding references, links and navigation elements. Use these techniques to help readers move smoothly through a user manual.
Modern online help authoring tools often have sets of ready navigation elements. For example, in ClickHelp, there are: breadcrumbs, mini-TOC, see also, next/previous topic links, etc. Using these elements in help topics allows creating a better user experience and turning technical documentation into a coherent system.
Conclusion
The ideas given in this article are quite universal. To create a perfect help topic, try perfecting its every part: a title, a body, images, navigation. The end result will not disappoint you.
Once you start applying these simple tips, soon you will notice that you don’t need any reference anymore - most of what we’ve mentioned here is quite intuitive.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices