Writing A User Manual (part 1) - Being Conventional (Page 5 of 5 ) Conventions in the document lead to patterns that the users can grasp.They then start expecting information in a particular format, thusincreasing their level of comfort with the document. Using consistentstyles also speeds up assimilation of the information, and helps spotparticular information easily on re-reads. - Headings: Headings are a powerful tool in making a huge mass of textlook manageable. A common model is that as you go deeper in a particulartopic, you indicate that by descending prominence of headings. So, alltop level headings will be, say, in a large font size and bold typeface,with the next level taking a smaller font size, and so on. You mightalso want to number the headings to help users understand the groupingof information.
- Styles: While a short piece of text requires only minimal use ofstyles (bold for highlighting, underline for warning), a tome asvoluminous as a user manual needs you to be much more creative. Youcould set conventions for indicating screen names, interface text ortext that the user needs to input.
On the other hand, too many conventions negate the purpose - remember,they should assist in quick reading and lookup, and they won't if usershave to keep recollecting what a particular style indicates. - Indented text and footnotes: This is text that is peripheral to thepoint that you are making - for example, background information on aconcept that you're introducing or a warning related to some functionalstep that you're explaining. Add these when you don't want to distractthe user from the main flow of information.
- Bullets and numbering: Bullets and numbering can also help to break upcomplex concepts into simpler, smaller information nuggets. Theconvention here is to use numbering for sequential information only (forexample, steps to perform a task) and bullets for other relatedinformation that is best presented in points instead of a paragraph.
Bullets also allow you to group together points related to a concept andascribe them levels of importance. Much care and consideration should begiven to the grouping of information in this manner - it could easily beas confounding as useful. - Terminology: A very, very important rule of creating end-userdocumentation is to be consistent in your use of words. For example, ifyou're using the word "function" to indicate the, well, functions ofyour software, you shouldn't at any point switch to "features","commands", "menu items" or "actions". To this end, make yourself aglossary of the terms that you're going to use right at the start, andstick to them consistently.
- Images and illustrations: Sometimes, a picture really is worth athousand words - and screen grabs, schematics or flow diagrams cansubstantially increase the efficacy of your document. Plan your usage ofimages and illustrations in advance, and be consistent in their usageand labeling.
So that takes care of preparation - all that's left now is to actuallybegin work. In the next, and concluding, section, I'll be discussing theprocess of actually developing the structure of the manual, togetherwith a sample table of contents, and also spending some time on documentrevisions, version management, and delivery. Make sure you come back forthat! Note: Examples are illustrative only, and are not meant for a productionenvironment. Melonfire provides no warranties or support for the sourcecode described in this article. YMMV! | DISCLAIMER: The content provided in this article is not warranted or guaranteed by Developer Shed, Inc. The content provided is intended for entertainment and/or educational purposes in order to introduce to the reader key ideas, concepts, and/or product reviews. As such it is incumbent upon the reader to employ real-world tactics for security and implementation of best practices. We are not liable for any negative consequences that may result from implementing any information covered in our articles or tutorials. If this is a hardware review, it is not recommended to open and/or modify your hardware. |
|
