Health Checklist for Your Technical Documentation
![ClickHelp Team](https://clickhelp.com/wp-content/uploads/2024/04/ClickHelp-Logo-Logo-only-Full-color-no-space@2x.png)
If you think of it, dozens or even hundreds of criteria can be used to determine the quality of technical documentation. This blog is actually more than us listing some criteria, this is an exhaustive guide you can follow to find areas of improvement.
We will look at this subject from two perspectives – from readers’ and technical writers’ side – because these experiences are closely connected. We will start with everything your readers expect to see when opening a user manual and how exactly you should present information to them. After this, we will approach writer experience and talk about how to organize processes correctly.
This article can be used as a checklist to measure health of technical documentation. The more items described further are on your list, the better. Unchecked items can be regarded as action points for documentation enhancement.
We can never know for sure what is going on in our readers’ minds when they are surfing the online documentation portal. Hopefully you are gathering reader feedback (we will talk about this later), but it is impossible to ask everybody what they think and even more so to please everyone. This is why we are going to lay out the basement for good reader experience so you can build on it later, tailoring it to your target audience persona.
Fonts
Fonts aren’t random. They are picked depending on purposes of a text. For user manuals, they should possess the following features: high readability, brand support and nice modern look. Where you can find the right fonts:
Color Scheme
It works similar to fonts. Colors on a technical documentation portal need to be appealing, not distracting. And, of course, a great deal of branding is done through a color scheme. Make clients’ transition across all resources smoother with matching color schemes. Check out great examples in the ClickHelp portal gallery.
Ways to get great color combinations are pretty much the same as for fonts:
Page Layout
A page layout has to be consistent throughout documentation. For example, if you have a default footer, make sure you add it to every help topic.
If you have several topic types (tutorials, code samples, ordinary help topics) used in documentation, it is better to make a distinct layout for each type and follow through with it. This will help readers navigate through documentation easier – they will know what is going on by just looking at a page.
Screenshots and Images
Make sure you have visual elements like screenshots to support complex instructions or, for example, flowcharts to help readers instantly see what a text describes in many words.
Walls of text are not sexy. Help readers digest information with the help of images, gifs, flowcharts, pie charts, schemes and infographics.
Videos
Documentation can contain video content. Videos significantly increase the value of user manuals. Here are types of video content you might consider including:
Landing Page
Modern user manuals require a landing page. In other words, a place where a reader can see all user guides available.
This page should contain:
Table of Contents
A table of contents is a great way to navigate readers through help topics. Intuitive and straightforward it certainly is a time-saver for many readers.
Several tips on implementing a TOC:
Navigation Elements
Readers love to roam around documentation freely, so let them. Equip your help topics with the right means of navigation. We talk about how to pick the right navigation elements in this article.
Here are the essential navigation items you would want to use:
Links
Links are a navigation element also. But we deliberately placed them in a separate section because of their importance.
Readability Score
The easiest way to check readability is to get a readability score. In ClickHelp you can have any help topic analyzed and get a score for it. The factors a readability test considers:
What you are getting at the end of this analysis is a computer-calculated index you can work with to see the dynamic and leverage text difficulty.
Paragraph Division
Paragraph division is easily overlooked. Keeping it one idea per one paragraph helps readers grasp the essential information very quickly.
Surveys and Polls
Surveys and polls can be used to get feedback from users. Surveys can point to weak and strong spots. Thus information can be used when making plans for further documentation development or making small changes right away.
Topic Rating
Don’t be afraid to add the rating option to your help topics. This has a lot of benefits. You can easily pinpoint help topics that need to be reworked and also you are giving the sense of control to your readers. They will know for sure that their opinion matters and they can actually influence things.
Comments Section
The most straightforward way to get useful feedback is through comments. Remember that if you have this option you will need to allocate time for answering the comments and taking action. This will have to be a two-way communication channel.
Social Media
This is, perhaps, not as common, to share documentation articles on social media, but we highly recommend having this option as it is just natural for modern people to be able to share things this way.
This is an important part of technical writing that influences the final outcome greatly.
Let’s start with a high-level investigation of help writing processes in your team.
Logic
Logic is the first thing you should consider when drawing up a documentation plan. High-level architecture is so important in the early stages of planning. Otherwise, you will have to redo the whole logic at some point.
Logic should be preserved in each topic and in the whole table of contents.
Topic Size
Size of topics is something you should also pay attention to. There’s no golden rule, but consider this: short topics occupy space in your TOC and can be restructured and long topics can be confusing for readers and should be broken down into several ones. Long topics can be used to explain super-complex concepts, but only as the exception to the rule.
Topics-based authoring helps readers a lot because one idea is meant to be explained in one topic.
Writing Process
Every doc team member should have a clear understanding of their tasks. That is, one sees what is done, what is in progress and what needs to be done. This is achieved through task management tools (like Jira) or using functionality of your help writing tool (statuses, assignees, email notifications, etc.).
Content Strategy
Content strategy deals with the general direction of your technical writing. This is what you need to understand a far as content strategy goes:
This is also a more general way to look at how the technical documents you author fit in with the company goals.
Consistency
Everything in your user manual has to be consistent. This makes it so much easier for readers to use and also shows your professionalism. A consistency checklist:
Creating a Documentation Style Guide is a great idea to keep things consistent.
Screenshots
We already mentioned screenshots as part of the reader experience. However, it is a good practice to establish some rules of screenshot usage:
These simple points will help you keep things organized.
Reviewer Role
Some companies do not have a dedicated reviewer role. We see it as a flaw. Not having a reviewer means that there is either no serious review process involved which has a negative impact on documentation quality or that these responsibilities are spread thin between different team members. Reviewing requires specific skills and it certainly takes time to refine a technical text. So, having a dedicated employee to do this job is preferable.
Review Workflow
If you have a Reviewer but lacking a real review workflow, you are not maxing out this process. The send-ready-text-to-Mary’s-email approach to review will take you nowhere. What you need is a stable workflow. Ideally it should be supported with your help writing software.
In ClickHelp you can set up a review process using:
Documentation Plan
Documentation maintenance is a collective effort of the whole technical writing team. For it to be successful, everyone should be fully aware of their scope of work, responsibilities and have a clear guide to follow. That would be a documentation plan.
Just like a brand style guide includes every rule pertaining to how your organization will present itself to the outer world, a documentation plan holds every piece of information related to help authoring in your company. It includes:
A good documentation plan becomes the main reference point, rids the doc team from the silo effect and creates a more streamlined workflow.
Single-Sourcing
Maintenance of modern technical documentation relies heavily on single-sourcing. This stems from Agile and Continuous Integration which in their turn lead to new product versions released quicker. Trying to keep up with this flow without a special tool at hand is a fool’s errand.
Single-sourcing should be implemented the earlier the better.
Global Find and Replace
This is a must have feature that gives you control over existing content. We have a thorough insight into how this feature works in ClickHelp here.
Basically, what it does is it allows you to make centralised changes in your content including source code, scripts, styles and links. Extremely useful for maintenance of all projects regardless of their size.
Changes History
‘Oops!’ moments happen to everyone when we delete from documentation something important. Version history is a valuable asset in this case. But there are more use cases:
Content Cleanup
Your technical documentation will grow and mature together with the product you are describing there. With new functionality entering the scene a lot of old features will be discontinued. Make sure to have a review process aimed at eliminating old topics or parts of topics that became useless.
Surveys and Polls
Surveys and polls work great not only with readers but internally, too. Create them to:
Cross-Team Communication
Other teams in the company may have a lot of first-hand experience with the documentation you’ve written. Or, they can have some feedback, as well. The support team, for instance, can become a great source of feedback.
Support engineers work with user manuals a lot and will be able to point out the weak spots. And they can also suggest areas to improve based on communication with users. Users can complain that there’s no info about a feature, or that it is overcomplicated.
We hope that you will find this checklist useful in your technical writing journey. Remember, there are always ways to make your user manuals better!
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices
Get monthly digest on technical writing, UX and web design, overviews of useful free resources and much more.
"*" indicates required fields