This is part of the Help Authoring Tips series.
The difference between a good help file and an ineffective one is not really how it looks, but ultimately, what is written there. Sure, the help should look good. This increases usability and makes a positive statement towards your company’s branding. But the contents of the help often determines the user’s ability to successfully use the application.
Following are some tips for writing right – correctly writing the help so that you maximize your user experience and minimize frustration. More, these tips will increase our efficiency making you an even more valuable employee.
- There has always been a debate about the value of adding screen captures and graphics in general into your help file. While I hope to discuss this in another post, here I’d like to offer one tip that will save time. If you are creating a help file from a Word or FrameMaker document, prepare in advance for the “graphics debate.” Naturally, all figures should be in a “figure” style. But even more that that, consider creating two figure styles (for example: figure and figureH). Then, as you write the document, analyze whether you want that graphic in the help file. If you do, apply one style (for example: figureH); if you don’t want the graphic in the help, apply the other style (for example; figure).
- As you write, watch out for phrasing that will slow you down later. If you are writing in Word or FrameMaker, be careful when you write something like, “In the following section” or “In the previous section.” In help – there is nothing preceding, nothing following. The topic stands alone.
- In help, remember that each topic is a standalone chunk of information. If you don’t tell your users how, why, or where – they won’t know. It’s not enough to describe how to propagate alarms and what propagating alarms means, you need to also tell them where to find the command.
- Separate your introductory text (when it is more than a short paragraph or two) from your procedures. People go to help to learn HOW TO do something. It is important to help them find this information as quickly and as clearly as possible. Cross references (hyperlinks) from each topic to the other will help the user as well.
- Format properly in Word (and FrameMaker) to simplify the import process. While most help authoring tools do their best to interpret what you intended – you can help this process by formatting correctly.
- Think of your global audience – simplify sentences to make sure the translation goes more smoothly, and avoid using culture-centric phrasing.
I could go on and on (and maybe I will in another post) but the best advice I can offer is to write clearly and follow standard technical writing best practices – keep your documents clear, consistent and concise!