Common mistakes in writing help and user guides
I recently overhauled a user guide for a client. It was chock-full of errors and broke just about every rule of effective writing. I don’t have the space to list them all here, but I thought I’d share the three most common mistakes with you.
Task-oriented or UI-oriented?
Perhaps the commonest mistake is to base the structure of the user guide on the user interface (UI). An effective help system is divided into task-oriented topics (the user guide) and UI-oriented references (the context help). For example, if the main menu or tabs are File, Views, Data, Reports, and Tools, you often see chapters titled “Introduction”, “File”, “Views”, “Data”, “Reports”, and “Tools”—that is, a UI-oriented structure. Whereas, the chapters should focus on the tasks that the user wants to perform, such as “Introduction”, “Understanding the interface”, “Managing data”, “Analysing results”, and “Customizing reports”.
In particular, several parts of the interface are often required to perform a single task. For example, exporting a customized report might involve creating custom views (Views), then laying out the views in the report (Reports), then setting up the page size and margins (File), and then exporting the page as HTML (Tools). So placing the instruction in the ‘Tools’ section (where the Export tool is accessed) isn’t really going to help the user to locate the information quickly.
Wordiness and redundancy
Here’s an example of an unnecessarily wordy instruction, quoted directly from the project I’m working on:
At this stage, it may be a good idea to save your work by clicking on the Save button, which you can find at the bottom-right of the page.
All very helpful, but the shorter the instruction is, the easier it is for the user to absorb it. All you really need to say is:
Remember to save your work frequently.
Two words instead of thirty-odd: now that’s an effective instruction!
Take the user from A to B
When instructing the user how to perform a task, tell them why, when and where before you tell them what to do. Here’s another example taken from my project:
Click on the percent Health value in the Scorecard on the Dashboard tab to display the results for that category.
Whereas, we need to begin by telling the user where to go first, and then guide them step-by-step in the precise order they would perform the task:
To view the results for a health category, select the Dashboard and, under Scorecard, click a Health value.
Note the order: it takes the user from start (point A) to finish (point B) and requires little effort by the user to interpret the instruction.
There are many more guidelines, but if you follow just these three, you will transform your end-user documentation. Remember that a well-structured and well-written user guide is the quickest and lowest cost way of reducing your support costs, improving compliance, and raising customer satisfaction.
October 8, 2015 / Tim McAuley / 0