We asked the Technical Authors at Cherryleaf for tips on writing Help files. These are their top 15 tips. 1. Think about what your audience needs/wants. Talk to your users. Find out what your users struggle with, what they already know, what kinds of information they crave, what tasks they perform most frequently, what vocabulary they use, what they are doing before, during and after using the system. 2. If you can't talk to your users, talk to your Help Desk and Training departments. 3. Plan your Table of Contents before you start writing. 4. Structure the Table of Contents, so that you users will find it is easy to navigate. Don't bury topics too deep - the user will never find them. 5. Write to a level of detail that is appropriate for your audience. Where possible, keep you topics short and to the point 6. Name your topics sensibly, so that a user can look at them and know what information they'll find within a particular topic. "General information" or "Miscellaneous" are no use to anyone. 7. Have just one procedure per topic. 8. Address your instructions directly to the user - avoid the passive voice. 9. Don't mix conceptual information with instructional information. 10. Use a style sheet for consistency. You can often use it again as a base for other projects, thus saving you time. 11. Use popups / expanding text / drop-down text to hide any information that will be optional for the user. 12. Avoid using indentation to indicate sub-sections. Use vertical white space instead. 13. Spend time on the index, as many users will look for topics here. 14. Include synonyms in your index. 15. Avoid use of large screen-captures. Instead, clip the image to show only the part being described. (c) Cherryleaf Technical Authors and Documentation Specialists 2006. |
