How to Write a Technical Manual that Users Can Actually Use

Transcription

1 How to Write a Technical Manual that Users Can Actually Use Robert Klimas Senior Engineer City of Toronto 2009 APWA International Public Works Congress & Exposition Wednesday, September 16, 2009 Columbus, Ohio The City needs a sewer and watermain design manual City of Toronto amalgamated in 1998 Total population 2.5 million residents Design and construction division needs one Development engineering division needs one Need a PDF version to go on intranet Former city Toronto Etobicoke North York Scarborough York East York Year of manual unknown unknown Development process of the manual Working Documents Workshops Create Draft Manual Technical Services Review Finalize Manual Manual Second Edition Manual First Edition 1

2 Benefits of a good manual Establish the roles and responsibilities Reduce procedural mistakes and costly errors Ensure consistency in operations Improve efficiency and productivity Train employees on their job function Serve as an orientation tool Do readers read manuals? Except for the true literati, readers are nothing of the sort: they are searchers. To do their searching, they start out as viewers or lookers. They flip pages, scan, hunt, and peck, searching for nuggets of information that they need and that might prove valuable for them. Jan White Document design no-no s 1. Underlining headings or words for emphasis 2. More than two typefaces in your manual 3. Two spaces after a period 4. All UPPER CASE headings 5. Lines longer than 60 letters 6. Text smaller than 10 point and larger than 13 point 7. Reversing text (white text on black background) 8. No consistency in layout from page to page 2

3 Typefaces Serif typeface Times Roman for text All valves on watermains equal or larger than 400 mm in diameter will be set in pre-cast waterproof concrete valve chambers. Chambers size will be shown on both the plan and profile drawing. Sans serif typeface Arial for headings All valves on watermains equal or larger than 400 mm in diameter will be set in pre-cast waterproof concrete valve chambers. Chambers size will be shown on both the plan and profile drawing. Structure and organization Text hierarchy three levels Hierarchy allows you to search easily Scan for information No headings numbering Headings to avoid Avoid headings that describe type of information rather than the topic Overview General More Information Discussion Results Basics Advanced Features Miscellaneous Policies Procedures Standards Guidelines Conclusions References 3

4 Readers scan for information they need Use styles modern feature of word processors Time saving feature don t try to produce any thing longer than a letter without using them Use the styles feature (don t apply formatting directly to elements of the text). It s faster and way easier to change. Using styles promotes consistency Use styles in your word processor Easier said than done. Who has the time to set up styles. The reference manual provided the styles in a template file. Heading 2 Use the callout style for margin notes. Module Title (Heading 1) Begin each module with an introduction briefly describing the information covered within the module. Keep it short. Use these for major headings within each module. Try and avoid using more than one or two on each page. Use the normal 2sp (2 space) style for regular text that comes just before a heading. Heading 3 This is the third level of heading and is used flush left in the text column. If you have a random series of items, use a bullet list: Use the bullet nsp (no space) style for single words or phrases. Use the bullet style for lists of complete sentences. Use the bullet 2sp style for the last item of a bullet list that comes just before a heading. If you have a step-by-step procedure: 1 Use the numlist style. 2 Use the numlist 2sp style for the last step before a heading. Heading 4 This is the fourth level of heading and is used flush left in the text column. Paragraph heading If want to identify the topic of a paragraph, just bold the first few keywords, follow it with a " " and away you go. You can use this after any heading level. 4

5 Rule of Tens To ensure that your manuals are easy to use and that information is easy to find, try to limit the following to 10 or less: chapters in a manual sections in a chapter sub-headings under a heading (at any level) steps in a procedure items in a list Avoid abbreviations of Latin phrases Abbreviation e.g. (exempli gratia) i.e. (id est) etc. (et cetera) English equivalent for example, for instance that is and so on, and so forth Capitalize proper nouns only People, objects and entities Formal names or titles we give to people and things Don t capitalize a word because you think it s important or you want it to stand out Get a copy Caps and Spelling and Stylebook by Canadian Press or Associated Press 5

6 Cross-referencing Cross-reference tells readers why they should look elsewhere, not where they should look. Example: For more information on using cross-references, see page. Not See page., for more information on using cross-references. Bullet lists Use bullet lists for three or more items. Capitalize the first word of a list only if the item is complete sentence Single space simple words or phrase list Double space list of sentences Do not use numbers or letters unless the sequence of the items is important (bullets imply random order) Keep track of items on style sheets Numbers spell number if under 10 Spell out names of units, for example 25 grams Use symbols, for example 25 g in tables Spell out % - percent or per cent And/or is often used in legal applications. Avoid using it where either and, or or or both will do. 6

7 Parentheses ( ) Parentheses are disruptive to the reader, so avoid them in your writing Example Students must return all materials (these include sample manuals and textbooks) to the instructor (Disruptive - avoid) Students must return all materials, such as sample manuals and textbooks, to the instructor. (Preferred) Creating an index is easier than you think Need 50 or more pages in your manual Readers prefer to use an index more than table of contents Printing and binding Give as much thought to the production (printing, binding, cover art and divider tabs) as you do to the contents. If you do, your manual is more likely to get the respect if deserves, because many people do judge a book by it cover. 7

8 Cover design A readers first impression of a manual comes from the artwork of the cover. Don t discourage readers from using the manual by making a poor first impression. This is the title page not the cover This is the cover 8

9 Designing covers is easy Divider tabs and binding Divider tabs are usually produced by bindery Binding go with the spiral wire not cerlox Pros and cons of methods of printing binders Method Trap sheets (inserted by hand) Trap sheets (sealed into the binders) Advantages less expensive extra binders can be bought when necessary print quality high binders can be reused high print quality with few design constraints more professional looking than trap sheets inserted by hand Disadvantages not as professional looking it takes a lot of work to insert the printed traps binders can t be reused for another purpose all binders required must be printed at same time 9

10 D-ring binder capacity (sheets) Size 3/4 1 1 ¼ 1 ½ 2 Binder spine width 1 1/8 1 ½ 1 7/8 2 1/8 2 7/8 20 lb. bond lb. bond lb. offset lb. offset Reference sources 1. Writing Revisable Manuals by Duncan Kent Carswell Publishing 2. Caps and Spelling by The Canadian Press 3. Stylebook A guide for Writers and Editors by The Canadian Press or Associated Press 4. City of Toronto Corporate Writing and Style guide 5. Templates 6. Photos Thank You Robert Klimas, P.Eng. Senior Engineer City of Toronto (416) rklimas@toronto.ca 10