Health Checklist for Your Technical Documentation

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.

Reader Experience

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.

Design and Visual Elements

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:

• Your corporate style guide
• Use a ready template from your help authoring tool
• Ask a designer to pick them for you
• Go to popular font resources like Google 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:

• Your company style guide
• Dedicated designer
• Pre-designed documentation template
• Popular web resources (colormind.io, paletton.com, coolors.co).

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:

• How-To Videos – instructions explaining how to perform certain tasks.
• Demo Videos – as a rule these contain an overview of a product or its features.
• Case-Study Videos – videos featuring your clients explaining how they are using your tool for achieving their goals.
• Webinars – long and in-depth tutorials, often held online. Documentation can have a section with video recordings of webinars.
• Promo Videos – a marketing type of videos that fit perfectly on the landing page of a documentation portal.

Navigation

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:

• A company logo
• A link to the main website (don’t forget that by using links like this you are improving SEO)
• A list of all user manuals
• (optional) This page can be restricted – only authorized readers will be able to find it

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:

• Use shorter and more meaningful node captions.
• Make sure the hierarchy is not too deep – otherwise readers can get lost in all the levels. Three levels sounds about right.
• Use custom node images (they can reflect your corporate identity or just look awesome :))
• Make sure the font is big enough. For the sake of keeping a caption’s length, some technical writers tend to sacrifice the font size. Don’t do that.

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:

• Mini-TOC
• Breadcrumbs
• Next/Previous Topic
• See Also
• Index Keywords

Links

Links are a navigation element also. But we deliberately placed them in a separate section because of their importance.

• Add links to your main website
• Cross-link help topics

Content Readability

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:

• Words length
• Syllables in a word
• Sentence length
• Terminology
• Etc.

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.

Reader Feedback Collection

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.

Authoring Experience

This is an important part of technical writing that influences the final outcome greatly.

Documentation Authoring

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:

• What information should be included in technical documents?
• What types of tech docs should we create (user guides, API docs, code samples, etc.)?
• How tech writing processes can be optimized?
• How do we find areas of improvement?
• What is the ROI of our user manuals?

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:

• Capitalization
• Punctuation
• Topic structure
• Design of tables
• Design of other elements (warnings, information boxes)
• Etc.

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:

• What information is considered sensitive and should not appear on screenshots
• What is the max size and weight of a screenshot
• How screenshots should be named
• Where they need to be stored
• Etc.

These simple points will help you keep things organized.

Review Process

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:

• Flexible user roles and permissions
• Topic statuses
• Customizable email notifications
• To-Do lists
• Review comments

Documentation Maintenance

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:

• Goals and objectives
• Content plan
• Time estimates
• Responsible people
• Workflow description
• Tools and resources (software used for help writing, links to style guides and websites)
• Glossary
• Delivery details (formats, means of distribution)
• Any other things that would insure consistency

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:

• Accidentally deleting content
• Deciding to go back to the previous version
• Checking who made edits

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.

Feedback Analysis

Surveys and Polls

Surveys and polls work great not only with readers but internally, too. Create them to:

• Understand how comfortable it is for your colleagues from different departments to work with the doc team
• See if communication processes between teams should be enhanced
• Understand how people rate technical documentation
• And, again, try to think of what can be improved.

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.

Conclusion

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