How to Write User Documentation and Help Manuals

What is user documentation for a company? We know what it is for end users – a place where they can get acquainted with product functionality, get their questions answered and generally find out more about the product. But what is the value of a user manual for a company? Here are some things documentation can do for your success:

• increase user satisfaction
• help with case deflection
• decrease the support team workload
• create a positive image for your company
• become a marketing tool

This sounds amazing. Alas, you should not think that any user guide will do this for you. It only works with the good ones.

Read further to learn the steps you could try and take to create quality user guides.

Step 1 – Planning

Audience

User documentation is some logically structured written text meant to be read by the users of your product that contains descriptive and explanatory data.

One thing for a technical writer to remember when determining the target audience for documentation is that it can differ from the product users. Let’s imagine a situation that you make an educational app for 4-6 year old children. Then, not the children will read the user guide, but their parents or a nanny. Or, you can create a separate guide for children (a colorful scheme explaining how to construct something, for example) and a thorough instruction for adults. The same works for products for the elderly – most probably, a granny will ask some younger people to help set up something using documentation.

At the same time, do not overcomplicate. In the end, we can’t satisfy each user, so we’ll try to do this for the majority of users then.

What difference does the audience make for the documentation writing process? Let’s see – user guides for b2b software should surely differ from the ones for kitchen supplies.

If your product aims at pros, then it should contain more terms, descriptions of complex features, and rare use cases. But, keep in mind that pros come in different levels of being a pro, as well. So, even if you user documentation is mainly for PhD’s, it still has to have all the simplest features briefly explained.

Let’s imagine a user manual for some kitchen supplies. You must include more visuals like plain schemes in such documentation. Text should mainly play the role of a structure building element while graphical elements have to explain most of the functionality or warn against improper use. Because no one needs to know all the peculiarities in this case. The aim of such a user guide is to help get the product up and running quickly.

Design

Now, at this stage, we are getting closer to the part explaining one way of user manuals being marketing tools.

The first thing to consider here is branding. If you are writing a user guide for software, it would be perfect to make it resemble the app’s UI.

In other cases, a good practice is using the corporate logo and color scheme.

Sometimes, you are not provided with a style guide. But you obviously still have to apply some color schemes and style your documents. Actually, creating a color scheme is not as challenging as it may seem, you just need to get acquainted with some basic notions like the color wheel. There are certain principles of color matching you need to become aware of, and you can make your user guide look good. You can read more on creating a documentation color scheme here.

When your documentation is visually synchronized with your brand it gives you a lot of benefits. Customers feel how solid and thought-through your business is as you pay attention to the smallest details. And, also, the users will see your corporate colors more often, memorize them and recognize when they see them later.

Structure

We’ve said a few words about the logic and structure in this post. But, as this point is crucial, we need to dig deeper.

The plan of the future documentation should start with high level things, and only then one should expand further.

A common mistake is trying to sort out all the material you have. A better approach would be creating a simple structure first and fitting in whatever help topics you have at the moment.

Of course it would be great if you could just create some documentation core and stick to it permanently.
But here’s what’s probably gonna happen in the reality: you’ll have to always be ready to adapt your user documentation to the ever-changing product. So, it makes sense to listen more to what the developers or PO’s have to say about its future. Then, you might be able to prepare the documentation structure for hosting more help topics that do not fit into the initial scheme.

The most efficient way to prepare for documentation authoring is to make up a documentation plan. This is a special document that will include every detail of your future user guide. Such documents vary from company to company. The following components are often included in such plans:

• Introduction. Here, you can mention the name of your new documentation project, define its purpose and objectives. It is also a good practice to specify where all the files are to be stored, how they will be delivered to the end users.
• Detailed Content Plan. Write down all sections and subsections of you documentation. Make notes if necessary.
• Responsible persons. Here, decide on people that are going to work on the documentation. Specify their roles and scope of work.
• Data management. Mention software, apps, websites that will be used to create documentation. Give links to relevant style guides.
• The workflow. Specify how documents are prepared for approval and what the approval procedure is.
• Time estimates. Consider the time-frames for this project and each task in particular.

Having everything in one place will help you manage the documentation authoring process even in a big team. Distribute this file across team members and listen to their feedback – you might wanna include something else for the points mentioned here are just some core elements.

Step 2 – Writing

We got all the preparations, it’s time to start actually writing. If you have everything planned thoroughly, than your transition to this next stage will be smooth.

If the transition has not been going great, we strongly recommend taking a step back and re-writing the documentation plan. Because, the possibility is very high then the further you move with your authoring process the more chaotic it will get without being able to lean against the plan.

If you feel like there are some predicaments but they are not critical, just manage issues as they appear, there’s no use in re-doing the whole plan in this case. There’s no such thing as a perfect documentation plan anyway. The idea behind it is to set the wheels in motion not to solve all the problems.

Step 3 – Testing

When you get your first version of documentation, you need to test it. The perfect way of doing so is to give it to a group of real users or people not involved into the development process and gather feedback. But, quite often, this step is skipped due to certain organizational difficulties, and user guides are tested only within the company. If your software documentation tool has teamwork features, then this process is easy to perform.

On a side note – don’t think that there’s really such thing as this ‘step’ called ‘Testing’. In fact, you will never stop testing your user documentation. It will be tested by real users, by the support team, by the documentation team itself, etc. after it is published. Be ready to deal with fixing bugs till the next documentation iteration and, maybe, even further.

Back to the topic. We’ve recently written a whole article on how to test user manuals. You can find a complete article here: Testing of User Documentation, while we’re going to give you a brief summary. There are several levels of user documentation testing. First there’s the safety check. You need to make sure that no harm can be done through your product and all the dangers are considered. The second level is checking coherence. Make sure that the logic is still in place and all the help topics are in the right places, and the info within them is as well. The last step is just some finishing touch with final spell-checking, UX face-lifting etc.

Conclusion

In this article you’ve learned about the main documentation writing stages. Creating a user manual is a long and complex process, and these guidelines are meant to make it a bit more approachable. This process will be different for each of you, but this plan-write-test combo is true for any use case.

Good Luck with your technical writing!
ClickHelp Team
Online Technical Writing & Documentation Tools