User manuals are complex documents that require a lot of up-front thinking and planning. They lend themselves to planning and development with mind maps.
A software user manual is usually written by a technical author, although often user manuals are written by product managers, entrepreneurs, programmers or other technical staff.
User guides for software mostly come in the form of a PDF or online help. They are often part of the last product experiences a customer has had with an application or company. According to the peak-end rule (Kahneman, 1993), as a software developing business, you need to see that the most recent experience in the customer journey is a good one. The last experience is the one that will be remembered most by the user.
Bad user instructions lead to unhappy clients, many support calls and emails, less worth of mouth marketing, more unsubscriptions and thus less money.
It will be much easier to on-board users and help them master your software with user-friendly instructions. Better documentation will lead to better engagement and higher customer satisfaction.
But how do you write user-friendly instructions? How do you make sure to include all relevant topics? How do you gather all the information from the subject matter experts? How can you do this in a structured way?
This is where mind mapping can be of great value. Compared to the traditional way of working, with mind mapping you will:
- Follow a more structured writing process
- Prepare your interviews with the subject matter experts in a better way
- Create a clearer overview of all product information to be included
- Be able to create your table of contents more accurately
In this article, I will tell how the writer of user guides can use a User Manual Template Mind Map to create software documentation that your users will love to use.
The user manual creation process
To help you get the most out of our user manual template, we’ll quickly discuss the software user manual development process:
1. Define initial requirements: The project starts when the software guide is requested from you boss or colleague. You then start with defining the document type, subject area/content, goal, scope, and intended audience.
2. Understand who the user is: The most important step in the process is to understand who the user of the user guide is. Your audience should always be at the top of your mind. He/she defines the text! Find out what the level of expertise is of the users and what terminology is familiar to them. Documentation for the backend of the web portal of a healthcare institution has different users than the end-user of health care that just wants to upload reclamation documents at the front end.
3. Map and plan the document: As software can be quite complex, its technical information will be extensive as well. To map out all the different user scenarios, functionalities and to answer the user’s questions, you can use a mind map. With a mind map you can develop the topics that your documentation will include, which will later be the table of contents. A mind map creates a visual overview before you start the actual interviewing and writing.
4. Interviewing the subject matter experts (SMEs): Once you have mapped out the main contents of your documentation, you can use this overview to interview the subject matter experts (such as the developers). They need to transfer all information they have about the software, if not yet familiar, to you. You might want to enhance your mind map with new topics that were not known yet.
5. Write the content: When the outline of the documentation is clear, the actual writing starts. This part takes the most time. Don’t forget that writing clear user manuals for your audience is an art. A common mistake many developers make when writing documentation, is that they want to show their technical knowledge and create very technical user guides or online help. See the section Usability Principles for creating user-friendly instructions on how to write user-friendly content.
6. Add visuals: Visuals, such as illustrations, screenshots, tables and drawings, are a good way to support, replace or augment texts or concepts that are difficult to explain when only words are used. .
7. Format the content: When the content (text and visuals) is ready, it needs to be formatted. User manuals contain several information types, such as safety warnings, instructions, and contextual text. By formatting the different types consistently, you help the user identify the information type. Besides that, the content will be published online or printed. You will need to create templates/skins/style sheets based on the style guidelines of your company.
8. Review carefully: To prevent several correction rounds and updates of the content, ask all people involved to conduct both a technical and grammar review.
9. Publish: When all content is approved and released, it can be published.
Usability principles for creating user-friendly instructions
Although there are many more usability principles, in this section we discuss the most commonly adopted ones. It is important to understand these principles and apply them for creating user-friendly documentation. Most of them are derived from the minimalism in technical communication principles (Carroll, 1982).
1. Topic based authoring: Topic-based authoring is one of the basic principles in technical communication. It is a modular approach to content creation in which content is structured around topics. These topics can be placed in random order and reused in different contexts.
A topic discusses a specific subject, and generally answers a user’s question. Therefore each topic has an identifiable purpose and can stand alone. Examples of topics in software user guides are:
- System requirements
- How to install the application
- How to do <Activity n>
2. Choose an action-oriented approach: This principle is based on the fact that users want to do things: they want to solve a problem such as installing an application or achieving a certain goal. That’s why your topics should provide users with an immediate opportunity to act. Focus on providing information which users can use to execute their task. Your user wants to do something and not to just read about it. Use active verbs and short sentences. Place only one instruction in a sentence (e.g., Click the SAVE button).
3. Anchor the software application in the task domain: Your software is just a tool that your user wants to use to conduct a task or solve a problem. The tool is merely a means and almost never an end in itself. That’s why it is important to think in activities rather than in a functional description.
The user will use the menu or table of contents to find out where information can be found on a specific task. It is important to use meaningful headings that will tell the users if they can find the answer to their question when navigating to the topic. The heading Exporting to an Excel File is much more user-friendly than Tips for Users.
4. Support error recognition and recovery: Making mistakes is human and users of software make many mistakes. As correcting these mistakes can be time-consuming, you should prevent mistakes whenever possible. The best way to prevent faults is through a better application. But even with an almost perfect product, mistakes will still be made. Therefore, give error information in your documentation. When your documentation is ready, you should conduct user research. Add error information there where it is needed. This information should help the user to detect, diagnose and recover an error.
5. Support reading to do, study, and locate: Users mostly use software to establish their own goals. Therefore you can’t describe each situation and build documentation mostly around just a few scenarios. It is often up to the users’ creativity to edit the settings and combine tasks to meet their own objectives. Besides this, a user almost never goes through a manual from beginning to end. Sometimes, users might read a manual to study; sometimes to check information, and at other times to help them with a task.
The software manual should support these different ways of consulting the manual. Some things you could do to support all ways:
- Round each topic off as a whole. Make sure that the topic answers the question that the users most likely had when they decided to read it.
- Place an overview of related topics at the bottom.
- Be brief and don’t spell out everything. By not explaining everything, the instructions will stimulate the users to activate relevant prior knowledge and to depend more on their own thinking.
How to use mind mapping software to create user-friendly user guides
Each product is different and thus user manuals contain much product specific information. However, the set up of a user manual for different products is quite general.
It is the task of the writer of the user guide, to get the product information out of the heads of the developers, structure it and write clear instructions.
This is where mind mapping can be of great value. By using the User Manual Template, you:
- Have a ready-to-use overview of the main topics that software documentation contains,
- Have a tool that helps you to interview the subject matter experts in a structured way.
- Will be able to enhance the content easily,
- Can further craft the ToC of your documentation,
- Can easily update the contents of your documentation in an agile way, and
- Can collaborate with other writers on the same project.
I have prepared a user manual template which is suitable for a variety of software manuals (see below).
How to utilize the user manual template
- Download the template in MindManager or XMind format.
- Modify it to meet your needs. Add topics that need to be discussed in your documentation and that you want to discuss with your subject matter experts.
- Share the mind map with the members of your technical writing team.
- Interview the subject matter experts and enhance/adjust the template.
- Finalize the topics and craft you table of contents.
Ferry is the director at INSTRKTIV. It helps brands to create compliant and user-friendly user instructions. Ferry is a blogger and regular speaker at conferences. Read his latest article about creating compliant user instructions.