|
But of course we're not going to be able to fully describe here all the ways of writing a good help system and avoid the mistakes that some technical authors make. However, here are some key factors that can help produce good online help:
 |
|
|
| |
 |
Create most help topics based on users' questions and problems. The main reasons that most users access the help is because they have an issue they need to find a solution for. |
| |
|
Choose your topics titles carefully. Help topic titles should reflect the question they answer or the problem they're trying to solve. |
| |
|
Identify your target audience, and then write the help using the language that the user feels comfortable with. Writing in a too formal style more often than not alienates most users, so don't do it; instead use straightforward, normal language. |
| |
|
Include plenty of ways for users to find the information they're looking for. Typically a table of contents, index, search facility, and related topic hyperlinks are required, but some help systems may benefit from breadcrumb links or browse sequences. |
| |
|
Make sure the help system is the right format, perhaps HTML help for locally-installed help or Webhelp for internet-based help. You may even consider splitting the help between locally installed components and online components. For more details, see Online help formats. |
| |
|
Make sure that the help system compliments other parts of the documentation solution, such as quick start guides, instructional tutorials, and so on. For more information, see User assistance. |
| |
|
Review your decisions on all of the above before you even put pen to paper or finger to key. It's much, much better to adjust your plan before you get into the project than later on when time is critical and rewriting can become expensive. |
| |
|
Remember the basics of writing high quality technical documentation - they apply to online help as much as to user guides:
| |
|
Use the active voice and present tense. |
| |
|
Be concise. |
| |
|
Ensure accuracy. |
| |
|
Stay consistent. |
|
| |
|
Always check and re-check the help system. If possible, get a technical review from the most suitable person or people, and not only check it yourself but get another technical author to review it if you can. |
Want to know more? For more information on how Armada develop online help, see Online help development.
|
|
|
