The art of writing a “user manual” for users not for us

Photo by Kelly Sikkema on Unsplash

Chances are if your products are more complex than a roll of paper towels, you create some kind of user documentation to help people learn how to use them.

A well-crafted, user-friendly product manual or user guide can mean the difference between a fantastic user experience and a … one.

Plus, user documentation isn’t just for new users.

Experienced users may also refer to user manuals or product guides to refresh their memories on a feature they haven’t used often or to solve a specific problem they have without complain on support channels or asking for new additional features.

It’s worth investing significant time and effort in writing a user manual so you can provide the best experience possible, but also have a common ground to evaluate the quality and set the expectations.

For this post, I’ll focus mostly on how I envision creating user documentation for software products.

I assume the reader knows a bit about product discovery.

I hope you will enjoy this article.

What is user documentation?

A user manual is a document provided to a user that helps in using a particular system, product or service seamlessly. It is also known as an instruction manual or a user guide. Such documents cover detailed information around:

• operations
• standards & guidelines
• troubleshooting guides
• functionalities & more.

User manuals usually contain step-by-step instructions guiding users through how to use your product and potential troubleshooting in case something goes wrong.

💡 User documentation is the content you provide end users to help them to be more successful with your product

Despite the goal of user documentation is so relevant for users to be more successful with our product, ask to yourself why we invest so little effort on writing quality documentation.

Reasons may include:

• Writing user manual is time consuming
• Writing a user manual is boring
• We do not have all information we need
• We do not consider documentation as valuable as it should be considered
• People write documentation in different forms making it less useful
• User manuals are written primarily for us not for users

Probably you have much more ideas on this, here my 2-minutes reflections.

Types of User Manuals

There are a number of different types of user manuals that can be used as examples when starting writing your own. Understanding first who are our target users and knowing what problems our users are going to solve make very easy to pick the best example.

Manuals can be for physical assets — an IKEA chair — or for intangible asset like software products, operation manuals or company-wide policies.

Example of a easy-to-use instruction manual

Based on the product, we can have different types:

• Getting started guide is a very simple and easy-to-use set of instructions to quickly start using a product: good examples are software products
• Instruction manual is a set of basic instructions that tells users how to set up and then use physical goods (e.g. IKEA or Lego instructions)
• Users manual is a set of pages that describe specific part of the product with focus on helping users to be more confident and successful with our product.

From the above type of manuals, we may derive others, like training materials, working procedures and so on. In the next sections, I’ll focus more on the users manual but I believe the same approach can be used also for any kind of “customer-facing” documentation.

How user manual supports your team

People working in IT, especially with cutting-edge technologies, always focused on improving existing processes, should keep in high consideration having great documentation and for me, after a year in Claims department of an insurance company, it is clear the central role of the user manual.

And more, the importance of having great documentation grows with the company growth as well as the teams.

At the time of writing, my users (200 active on daily basis) write questions on a slack channel or directly to product team; in some cases, they are bugs, but sometimes they are misunderstanding the way the product works.

The documentation supports all people, not only the ones who actually use the product itself, but also the tech team as well as the product team, especially when the domain is overwhelming.

To summarize, the great documentation helps in the following major ways:

• Gives an easy reference guide
• Reduce questions only to relevant ones
• Change the users’ perception of product from an always-in-construction item to a professional product

What makes a good user manual?

Plain language

Your writing should be clear, simple, and easy to understand, without requiring a dictionary to get through. Use short sentences and words to make your text accessible. If you have to use a technical term, make sure you define it or link to a glossary.

Don’t write as if they’re children, but understand that they are using our product for their daily work

Avoid mixing languages

Especially in non-English documentation, we have the habits to mix Italian content with English words. Don’t assume your users know/have the same level of knowledge of English, product jargon or expressions we use during the development; they sound natural for us, for them maybe not.

Remember who are our users and consider replacing content with easier native speaker words, or, when impossible, make sure you define it somewhere or link to a glossary.

💡 Replace complex jargon with native speaker words or, when impossible, make sure you define it somewhere or link to a glossary.

Simplicity

Keep documentation as simple as possible to achieve its goal. This applies both to the document’s content as well as its design. Long blocks of text and pages tightly packed with written and graphic content can make user guides or manuals feel intimidating and unfriendly.

💡 Users who are intimidated by your user materials are far more likely to call your support team for help than they are to try to solve their questions on their own.

Visual

Without visuals, your user manual will end up being a long wall of text without anything to break it up or catch the attention of your users. Make your documentation interactive by adding relevant images, diagrams and videos for your users to engage with. Make it clear which step of the instructions your visuals are referring to so users can make sense of them.

💡 Adopt as much as possible visual aids as “simplified” graphics or real example of the product

Logical hierarchical structure and flow

Your users need to be able to search through your user manual using a predefined sense of structure to guide them. Your contents should have a logical hierarchical structure that makes sense to users when they are looking for information.

💡 Start with the easy stuff first and then, as the users gain more knowledge, show them advanced features.

Clear topics and relevant articles

You should organize your content into clear topics that make sense for the article. You should not have too many topics in a single article of your documentation otherwise could be overwhelming for users. Focus only on the problem you are going to address in the current article!

Feedback and reviews

Actively seek feedback from your users on your user manual and take their suggested improvements into account. Find out whether your users are actually being successful with your manual and whether it is enabling them to solve their problems.

💡 Add quick access link to your documentation on your product and monitor the adoption with Google Analytics

How to create a great user manual

Identify the users

The first thing you need to do when writing your user manuals is about identify exactly who your users are, their needs and problems. Finding out who your audience is, it tells you how much detail you need to include in your user manual, their daily activities and the way that your content may speed up their activities.

Focus on the problem

All user manuals are aimed at solving a problem for users. You need to find out what these problems are in the first 1 or 2 sentences in order to create a truly helpful manual, and solve the problem with your instructions.

Use sequential steps in order

Your instructions should be broken down into sequential steps that are presented in order as a numbered list. Try organizing it so the easiest task to accomplish is presented first.

Keep just one point per step to make it easy for your users to follow the instructions. Tell your users what the completed task will look like before they move on to the next step.

Adopt the same template

To keep your documentation consistent, it’s important to use the same page template. Your template should be clear and easy to follow, and include the vital components needed.

The template can include:

• Introduction (problem to solve)
• Table of content
• Sections and subsections
• Sequential steps
• Warnings and call-outs
• Additional information and links to additional pages.

Treat all users as laymen

Don’t assume that your users have a technical background — the language you choose should treat the users as if they are laymen, avoiding all jargon and specialist terms unless absolutely necessary. It’s best to assume that your users know nothing about the product and be as explicit as possible in your documentation.

Build content using a practical approach

When writing your user manual, make sure you include practical examples alongside your instructions to show users the results they can expect to see if they complete the task. Your instructions should clearly explain what users will see or hear and any feedback they might get from the product.

Explain symbols, icons and codes early

You may need to use symbols, icons and codes in your documentation to represent certain information. Make sure you explain them early on so users aren’t left scratching their heads.

From talks to a product initiative

At beginning we said the purpose of writing great user manuals is all about helping our users or customers or our teammate to be more successful with our product, so as well as any other product initiative that enhance user experience, writing a user manual has the same goal with the only difference being live content.

In defining the activities of writing a user manual, I imagine these steps:

• Plan content
• Write user stories
• Review content
• Measure and iterate

Plan content

“No plan, no party”: in our world discovery and planning are the key activities of product management. Documentation is a backlog item to keep in mind during the discovery activities and must be planned as well. It is not enough to plan just the whole activity in a defined time frame, it is mandatory to define the structure of contents, share with the team and start doing it.

Below an example of planned contents.

Different methods can be used for defining the backbone of user manual, in the example above we choose to split among main user journeys.

Write user stories

As for any other product activities, we may use an agile framework to deal with writing user manuals.

The structure of user story may be:

• Target users
• Description of section to write
• Acceptance criteria

Let’s start with “Target users”. It is a simple list of interested users. The reviewers should check this list and see if the writer has considered all groups.

Then we have a “Description” section where you find a very short description, in gherkin format, to explain the scope (the problem) to solve in 1 sentence.

And last, the “Acceptance criteria” section.

Here you will find how to review the work done; criteria will be discussed in the next section “Review content”.

Review content

The problem of these user stories is how we evaluate the “done” and the “value”. The idea is to define a framework which supports the reviewers to judge the content written and make changes when required. The framework defines two main topics:

• How we evaluate content
• Which are the key items to be evaluated

First topic: how we evaluate content

The evaluation is based on a simple evaluation schema made of 4 levels:

1. Scope missed, rework required
2. Scope needs some updates, my comments are reported in the document
3. Scope is clear, (I executed) small corrections and additional enhancements are reported into the document for review.
4. I understood everything or I am able — when applicable and given the product — to perform basic tasks without any support.

Second topic: items to be evaluated

These areas shall be evaluated; I reported some possible questions to help reviewers to clarify how:

Plain language

• Is the content well written, easy to understand for non-technical people or without my deep knowledge of context?
• Are technical terms defined in a glossary?

Mixed languages

• Are there any words that can be rewritten using users’ target language?

Simplicity

• Are there repeated parts that can be reduced to common ones?
• Are the sentences short enough?

Visual

• Is it a drug recipe or software product?
• Are the relevant images presented in the right places with captions when the purpose is not easily understandable?

Logic hierarchical structure and flow

• Is the structure clear and does it show a logical organization?

Focus on problem

• Is the problem clearly defined in the first 2/3 paragraphs?

Identify the users

• Is the card targeting the right users?

Uniform documentation structure

• Is an introduction available? (the one with problem described)
• Is a table of contents available?
• Are the contents organized in sections (H1) and subsections (H2/H3)
• Are the relevant contents written using visual aids like call-outs or warnings.
• Is additional information or contact us section available?

The final (JIRA or YOUTRACK) card may look like:

Measure and iterate

As well as for any other product item, we may collect some metrics. I believe “adoption” is the first one and easier to start measuring: just use some tracking tool and watch how many times our users click on the documentation link from our product!

It is a little trickier having a specific feedback on some sections, especially at the beginning and mainly based on the users. Always add a section like the one shown in the picture to ask for feedback.

An example of asking users’ feedback

Conclusion

User manuals are an indispensable part of your product or service and you should allocate appropriate amounts of time and effort to its creation.

Delivering a helpful user manual will result in more satisfied users and helps to minimize the number of contacting requests to the help desk.