Technical Writing- Steps involved in User Guide Preparation

The user guide assists the end-user on how to use a product or service. It is usually prepared by the product manufacturer or the service provider. There are many types of user guides, such as an installation manual, a user manual, a service manual, and more.

The user document preparation involves four steps:

1. Draft a plan
2. Create the guide and do a self-review
3. Review the guide with technical experts and revise it
4. Update the document periodically

Start with a plan

Every work has a plan. Likewise, the documentation work must be planned, which includes audience analysis, content creation, and so on.

Audience analysis: Decide on your audience before writing a document. The document prepared for a technical person is different from the one created for an end-user.

For example, if you are writing an owner manual for a bike, you have to include the basic details of the bike, such as fuel tank capacity, indicators, tool kit, and so on. This owner manual is prepared for the end-user.

If you are writing a troubleshooting manual, you have to include the issues, probable causes, and troubleshooting procedures. The troubleshooting manual is prepared for the service engineers.

Purpose: Based on the audience (user), understand the purpose of the document so that you can gather the required information for the user manual. Examples of a document’s purpose can include how to use a mobile application or how to install a software application, and so on.

Style guide: Determine the style guide you are going to follow for the documentation, for example, the Microsoft Manual of Style.

Topics identification: Try to list down the main topics you would like to cover in the user guide.

Tools: Decide on the tool to use while preparing the user guide, for example, Adobe RoboHelp, Adobe FrameMaker, and so on.

Prepare the guide

After you list down the topics of the document, gather the relevant information from the SME or any source documents, and prepare a draft user manual as per the style guide.

Always remember to maintain the logical flow in the document. Your language must be simple; only then can the document be used globally. In aviation documents, the technical writers use a standard called Simplified Technical English (STE) to make the language simple.

Make sure you include all the required information and supporting diagrams/screenshots so that the user gets connected with the content. After you prepare the draft user manual, always do a self-review to rectify errors.

It is mandatory to follow certain rules. Some of them are listed below:

• If you use acronyms, always provide the full form, at least for the first time.
• Use simple language. The document must be legible to users whose first language is not English.
• Use a commonly recognized technical writing style guide such as the Microsoft Manual of Style. If your organization has its style guide, adhere to it.
• Do not assume that the user is familiar with the product. Explain the instructions step by step for easy understanding.
• When you are instructing the user to do some activity, always start with a verb.
• Ensure there is only one instruction per step to avoid ambiguity.
• Use graphics to show main actions and objects.
• Special Notice: It is mandatory to alert the users when they perform certain activities. Use the special notice signs approved by the organization you are working on:
  • The Caution sign indicates a minor risk of injury or damage to equipment if proper safety practices are not followed.
  • The Warning sign alerts the user of major hazards that may cause severe injuries or death.

For more rules and styles, please refer to the Microsoft Manual of Style.

Arrange the topics and sub-topics

Post content creation, arrange the topics in a logical sequence and mark the headings and subheadings with the respective styles.

If the user has to perform a task, make sure you provide a numbered list so that the user follows the activities step by step.

Decide for which audience you are writing a document. The document prepared for a technical person is different from the one created for an end user.

If it is not necessary to follow a sequential order, make sure you provide a bullet list, such as a list of rules.

A typical user guide has the following sections:

• Table of contents- It shows all the sections in order. It also allows you to navigate to any section directly. In a word document, click References > Table of Contents to add a TOC to the document.
• Pre-requisites- It is a list of preliminary requirements. For example, before you install software, some system requirements are mandatory.
• Precautions- They are used to alert the user before they perform a job, such as a warning.
• Procedure- It is the standard procedure. For example, the procedure of using an application.
• Appendix- It provides additional information, such as related documentation.

Review the guide

If possible, ask an employee who is new to the product to use the document and get their inputs. Revise the document if the inputs are noteworthy.

The user guide must be reviewed thoroughly by the technical team. If they share any additional inputs, revise the document accordingly and get the document reviewed by them again. Apart from the technical content, the guide must be reviewed for language and grammar by senior writers.

Update the guide for new features

When the product gets updated with new features, you must update the document accordingly and get it reviewed by the technical team and senior writers. In this case, the updated sections are only reviewed. Maintain all the versions of the documents in a repository as prescribed by the product owner/organization.