From a User "Misguide" to a "Guide"

User Misguide? 

a user guide is supposed to assist end-users in completing their tasks but if a product- help fails to communicate what it should, it can’t be called a User Guide / Manual.

 The Art and The Artists of Writing 

The Technical Writers do know how to talk to their audience and hence the guides they produce are clear in conveying the instructions. However, in some cases – generally for low-budget projects, professionals for content authoring are not available and therefore, such activity needs to be handled by same person who is supporting / handling the product / application.

Not a Writer but CAN Write

If you are one such individual, not a Technical Writer, who has to write a User Guide, write it with confidence. Here I have shared some tips to help you in writing a, good-enough, guidebook.

To start writing, read first - the points below:

Point # 1. Target Audience and Prerequisites: Depending on the application you are writing a user guide for, the target audience may vary and so the prerequisites. If you know who they are, you can safely decide to leave certain details and include only the relevant information.

Point # 2. Assumptions and Environment: Even if you know that your audience is knowledgeable, it’s still good to specify assumptions. Sometime a procedure valid for a specific version of a solution may not work completely in its previous or advanced versions, so specifying the environment in which the instructions work perfectly actually leaves good impression.

Point # 3. Learning Objectives: If you set the expectations in beginning, end-users after following the instructions could determine if they have learned the subject matter or not. Write the learning objectives clearly no matter how minute they are in your thinking. 

Point # 4. Optional and Mandatory Steps: Typically, not everything a user performs in a system is necessary. So if you have a step, which isn’t required, but add some value, do mention it with the reason why its good to be performed to let user decide whether to get the associated benefit / not.

Point # 5. Action (Choose, Select, Click, Press): The actions an end-user is required to perform, while completing a procedure, may vary from screen to screen; sometimes the requirement is to use a menu item and another time to use the keyboard. Be clear with the use of verbs. 

If there are options such as the radio buttons, user may need to Choose. If it’s a list, user may need to select. Some items may require left / right mouse-click, some may require single / double click. Similarly sometime, you need to Press a button on keyboard and sometime on a menu.

Point # 6. Emphasis (Screen Marking and Headings): A user may have difficulty in finding an element, which require user’s attention, so mark the necessary parts of the screenshot with clear signs. On the other hand, certain steps are major while others are minor. Use headings to differentiate between them. 

Point # 7. Tips and Tricks: Some of the tasks could be accelerated in some systems by following specific actions. If such scenario is valid in your case, do mention such tips. Generally, a ‘bulb’ sign is used to highlight the tips in user manuals.

Point # 8. Alternatives: Mouse-Click / Keys Combination: Some of the activities could be done in different ways. As some users are more comfortable in using the alternates so do mention the alternatives. Highlight them to facilitate users. For instance, if a step could be performed through a “mouse-click” and a “key”, do mention both.

Point # 9. Steps – Instruction, Screen Reference: When you refer to an element on screen, use the same structure as in the screen. For instance, if a menu item is in CAPITAL words, in the instruction refer it in the same way. If its an abbreviation, you shouldn’t mention its full equivalent.

Point # 10. Screens: Information and Dialogue: Differentiating between an information pop-up and a user action is always required. In a single activity type, it’s possible a user sees more than one screen. Specify clearly where an action is required. You may add some icon to differentiate between the types.

Point # 11. Numbering / Reference: Within a procedure, sometime you need to get back to certain steps to perform a similar activity. Having number assigned to each step could help you in referring user to previously performed activity easily.

Point # 12. Summary: At the end of the user manual, summarize the key points which a user should have learned by following the instructions. It could be similar to the learning objectives (you mentioned at the start) but in different tone.

Add your points

The Subject Matter Experts - the Technical Writers, are more than welcome to comment to refine the topic further and help those who are going to write a technical guide. 

About

Faisal wrote the first User Guide in 2002 for some SAP Users and the latest last week describing the Pivot Table. In between these two periods, he also developed quite a few training documents, most comprehensive of which was at a Train-the-Trainer program (at a large-scale business transformation project) where he developed detailed presentations, user guides and e-learning material.

For details on his professional credentials, please visit his e-portfolio at www.saphcm.net or contact him at his email: faisal@saphcm.net.