How To Write An Effective User Manual

Posted : admin On 12/21/2021

Nov 17, 2008  The manual writers should be a part of the design team. Ideally, the manual is written first, aimed at being short, simple, and understandable. The designers and engineers help oversee the writing, for when the manual is complete, it will serve as the product specifications that they will follow. Nov 22, 2019 A user manual is a formal writing piece with a specific structure, and should be written by someone who is intimately familiar with the product such as a technical writer or the product designer. Writing an effective user manual requires knowing who is going to be using the product, then writing it with these users in mind.

  1. How To Write An Effective User Manual Download
  2. How To Write An Effective User Manual Youtube
  1. Jun 04, 2007  Ensure that the user manual can lie flat on a work surface when opened. Consider the environment of use and if necessary provide a robust user manual. Consider whether the user needs to hold the user manual and work at the same time. Provide durable covers and pages. Consider whether the user manual needs to resist water, oil, dirt, grease etc.
  2. You can't write an effective job training manual until you understand how the job works. Ask employees who do, or who have done, the job to talk you through the daily process. Talk to supervisors or managers to get their take on the job's primary duties and objectives. Find out how someone in the job interacts with other people and departments.

Contents

Know who you are writing for

If you know who your target group is, you know two very important things that are necessary to write a high-quality user manual.

First, you know something about the tone of voice. If you are writing a user manual for first-time users of an alarm system, it could be that you need to explain how to set up the sensors in a room. You should motivate them to have a look at several examples so that users can use the sensors effectively. This requires setting up some kind of motivational relationship with the reader so that he/she gets the most out of your product.

However, if your product does not need an introduction because users will be familiar with it right from the start, you could leave out examples or any advice to experiment. Your language could be more business-like, just pointing out where the relevant buttons are.

The second consideration aligns pretty well with the first point made. Any target group values its own level of detail. It is not necessary to explain to maintenance personnel how to clean a manufacturing machine. People from this group would be offended if you would spell out what to do. However, it is necessary to tell personnel from a small company how to replace printer cartridges. Or to inform them when a printer would need internal cleaning.

It is always important to keep in mind who you are writing for.

A good start is your Table of Contents

Why is a Table of Contents a good start? Because a Table of Contents forces the writer of a user manual to think about what he/she wants to say in what order. Of course, there will be a foreword or an introduction in any user manual. Without doubt, there will be safety instructions at the beginning of the manual as well. There will also be some maintenance issues at the end. But what should you put in between those chapters?

This all depends on the product itself. For some products the settings are important: one day a pump may work ‘normally’, another day it may be best to set it in reverse. This could depend on water levels, for example. A chapter called “Everyday settings” could be appropriate here. Another chapter may be about collecting information how much water has been transported and to where exactly. One could call such a chapter “Monitoring results”.

Take another example: a so-called ‘multifunctional device’. For a ‘multifunctional’ the chapters in a Table of Contents could be based on, indeed, its different functions: printing, copying, scanning, faxing, and so on.

As long as there is some logical order that the user can relate to, the user manual lends itself for effective scanning. In this respect, it is absolutely essential that each chapter and each paragraph has a clear-cut title: “Printing using your computer”, “Copying without your computer”, “Scanning to your computer” and so on.

Collect all necessary information

A technical writer has the reputation of being inward looking, interested as he/she is in only one thing: technology.

This reputation does not do him or her justice. A technical writer should know a lot about voltage, current, resistance and megahertz. But he should also know how to collect all the necessary information. Quite a lot information may be available on paper or digitally. One could think of a risk analysis, 3D CAD illustrations, data sheets and so on.

But it is quite possible, even probable, that this information does not answer all the questions a technical writer has in mind. After all, a technical writer wants to place himself in the shoes of the user. If the documentation does not elaborate on the need for a pump to be set in reverse, he needs to ask the experts: why is it necessary to set this specific pump in reverse?

This means a technical writer has to have communication skills. He also has to have social skills. Placing yourself in the shoes of another person has everything to do with wanting to know the other person.

Portraying a technical writer as a ‘technician only’ would be a mistake. It takes more to write a user manual than being ‘tech savvy’.

Actually writing (illustrating?) your user manual

OK, you have collected all necessary information. Now it is time to actually write your user manual. Three considerations spring to mind.

The first consideration has to do with minimalism. Minimalism is a philosophy not to spend more words on a subject or task than is strictly necessary. It is not necessary to tell the reader that a valve is available in three colors when the only valve on a tank is red. A user only needs to know how to use the valve and when. This may sound very obvious, but proves to be quite a challenge in (too) many cases. Some companies do not throw away their ‘marketing head’ easily.

The second consideration is: always use Simplified Technical English if you want to be business-like. Simplified Technical English, or STE for short, does away with words that are ambiguous, such as ‘to carry out’. ‘To carry out’ could mean ‘taking something away from a certain location’, but also ‘taking action’. In STE, only the verb ‘to do’ will do. Also, STE limits the number of words in a sentence to roughly 20. This make any sentence easy to understand.

User

The third consideration is also very important. Why use text if an illustration works just as well or even better? After all, an illustration takes away the need to translate text. But even more important is the fact that people are first and foremost visually oriented. The saying ‘A picture tells you more than a 1,000 words’ implies that people grasp the meaning of something faster and better when it is illustrated. You cannot present all information visually (“Be sure the holes are free of wood chips and saw dust”). But where you can, the benefits for the user can be enormous. Thus, ‘writing a user manual’ takes on a whole new meaning.

Choosing the appropriate format

There still is one choice left: what kind of layout do you want? Or, in jargon: what is the template you want to define so that your user manual not only matches the wishes of the user, but also your corportate identity? Consistency is key here: every chapter and every paragraph should look the same.

There are software tools available that help you to define a professional template. What’s more: there are content management systems on the market that can transform a single source text into any format required, whether this format would be an A5 booklet, an A4 book, a PDF file (portrait or landscape) or a website that adjusts itself automatically when presented on a computer or tablet or smartphone.

Companies that are specialized in writing user manuals know how to help you choosing the relevant formats – in case you would need advice.

In a previous article, I went over 14 examples of documentation mistakes you might be making. Today, I'm going to show you 10 examples of what makes great end user documentation.

I should clarify that end user documentation does not serve the same purpose as technical documentation, so you shouldn't write them the same way. Technical documentation is meant to teach somebody everything there is to know about a subject, whereas end user documentation is meant to just show somebody the necessary steps to accomplish a task and answer 'How to...' questions.

The examples I show are examples of what makes great end user documentation.

1 - Write great titles

Great end user documentation consists of titles that are specific, and often in the form of performing a task. This not only makes it easier for your end users to find what they are looking for, but it helps you write better articles.

For example, think about how much time it would take to write an article titled 'Contacts' - you wouldn't know where to start. So you create an outline of all the 'Contacts' topics you can think of, take screenshots of the Contacts object, explain all of the menu options, and write a history of the Contacts object - all useless to an end user who just wants to know how to create a partner contact in Salesforce. Instead of going right to the information they need, end users will have to sift through all of the other stuff to find an answer.

If each article has its own, great title, then your end users can quickly answer their own questions by performing a keyword search or by browsing through your table of contents.

HubSpot does a great job writing useful titles, and then demonstrating the workflow using pictures, text, and annotations. Their documentation is a great example of how to write end user/customer documentation.

Tip for writing great titles

To continue the example from above, instead of writing one big article titled 'Contacts' just write a dozen little articles that each answer one specific question:

  1. What is a contact?
  2. How do we use contacts?
  3. How to create customer contacts
  4. How to convert a lead into a contact
  5. How to create partner contacts
  6. How to create an account for a contact
  7. How to merge duplicate contacts
  8. How to import contacts from Outlook
  9. How to import contacts from a CSV file
  10. How to add contacts from Gmail using Cirrus
  11. How to change the Contacts view
  12. How to log a call with a contact

These are so much easier to write, and your end users will find them much more useful because they can quickly search for, and find, answers to their specific questions (end users need specifics). Plus, you can always combine a lot of little articles into a larger workflow and organize them into a chapter or a manual.

2 - Use annotated screenshots

The majority of end user documentation should have screenshots, and those screenshots should include some sort of annotation. Adding an arrow, a circle, or number sequences can make end user documentation completely dummy proof, and save end users from having to figure out what to do.

Even if it seems obvious to you where to click, including a few simple annotations will go a long way in removing confusion.

3 - Use video AND screenshots AND text

How To Write An Effective User Manual Download

If you have the budget, the patience, and the time, you can do what Wistia does - create a video explanation, then include step-by-step instructions underneath the video.

This is a great way to do end user documentation. The video acts as a teacher to explain an overall process and provide some initial training. But after the initial training, end users don't need to watch the entire video again - they just need a quick reminder of what to do. The step-by-step instructions are great for the quick reminder.

4 - Include links to related articles

When you reference another action, product, workflow, or term, it always helps to include a link to the related article. Otherwise, end users waste time searching for what you just referenced.

5 - Easy to browse

if you only have 10-20 articles, then you don't really need to make them easy to browse. It's when you have over 20 or 30 articles that you really want to make a nice Table of Contents - especially if your documentation is online.

When your end users don't quite know what to search for, they can browse your documentation to find an answer. In this example, Metric Insights has organized their manuals into sections, and then each manual is broken up into chapters and articles.

How To Write An Effective User Manual Youtube

6 - Easy to search

Google has spoiled everybody. When your end users know what they are looking for, they expect to be able to type in a keyword and find an answer. If your documentation isn't searchable, then it's not going to be used very often.

7 - Easy to find

Below is an example of the ScreenSteps integration with Salesforce. It provides links to articles based on which Salesforce tab is open so end users don't have to go very far to find relevant documentation. Plus, it has a keyword search feature so end users can type in their question and search your ScreenSteps documentation for an answer.

The faster end users can answer their own questions, the less time you'll have to spend answering them yourself or showing them where the answers are.

8 - Show the end result

At the end of it all, what is the end user supposed to see? Here, Skuid does a nice job including a screenshot of the end result with a brief explanation to help end users determine whether everything was done correctly.

9 - Show the steps and substeps

Including step numbers makes it easy for end users to follow along and piece together what they are doing. You can also take advantage of sub-steps to make your documentation easier to follow.

10 - Unique URLs for each article

If you were to click on this URL - http://help.screensteps.com/m/salesforce/l/211489-add-contextual-help-and-search-in-salesforce you would be taken to the exact article you need to answer your question about how to create a campaign target list. This makes it really easy for you to respond to questions with links to your documentation. Otherwise, you have to say, 'Download this PDF, go to page 47, and on the 3rd paragraph you'll find an answer.'

With a unique URL, you can respond in Chatter, email, in the communities, etc. sending your end users to the exact answer they are looking for.

Why do any of this?

The goal of your end user documentation is to reduce the number of hours you spend explaining workflows, and reduce the number of hours end users spend looking for answers.

If you can remove hurdles your end users have to jump over in order to find answers, they will reference your documentation. And that will create self-sufficient end users who do the job correctly, in less time, and without constantly involving you.

Note: HubSpot, Metric Insights, and Skuid all use ScreenSteps to write great end user documentation.