How to Write User Documentation

The following is the table of contents of the Test Documentation. It is intended to indicate the scope and level of detail of the document.

1. INTRODUCTION........ 4

1.1. USER MANUALS ARE NOT TECHNICAL....... 4

1.2. WHY WE NEED GOOD USER DOCUMENTATION...... 5

1.3. MANUALS WRITTEN IN THE EARLY STAGES... 5

1.4. PRACTICES WHAT IT PREACHES.... 6

1.5. OBTAINING COPIES OF THIS MANUAL.... 6

2. PREPARATION ...... 7

2.1. SOURCE MATERIAL ..... 7

2.2. DOCUMENTATION PROJECT PLAN..... 8

2.3. PROJECT PLAN ........ 9

2.3.1. Document name (section 1) ....... 9

2.3.2. Purpose (section 2)...... 10

2.3.2.1. Instructional mode ........10

2.3.2.2. Reference mode........10

2.3.3. Table of contents (section 3).... 11

2.3.4. Deliverables (section 4)....... 11

2.3.5. Resources (section 5)....... 11

2.3.6. Nature of the software (section 6) .... 11

2.3.7. Scope (section 7) ..... 11

2.3.8. Topic (section 8)...... 11

2.3.9. Who is the audience? (section 9) ..... 12

2.3.10. Document set (section 10) ....... 12

2.3.11. Presentation (section 11)..... 13

2.3.12. Project schedule (section 12)....... 13

2.3.13. Software (section 13)....... 13

2.3.14. Editing (section 14)..... 13

2.3.15. Budget (section 15) ..... 13

2.3.16. Copyright (section 16)..... 14

2.3.17. Translation (section 17) ...... 14

2.4. ESTIMATING..... 14

3. THE WRITING PROCESS....... 16

3.1. CLEAR & EFFECTIVE COMMUNICATION ...... 16

3.2. NO TIRED FIGURES OF SPEECH.... 16

3.3. SHORT NOT LONG WORDS...... 16

3.3.1. Economical & precise with words.... 17

3.3.2. Active not passive........ 18

3.3.3. Everyday English not foreign, jargon or scientific... 18

3.3.4. Prefabricated language ....... 19

3.3.5. Present tense not past/future ....... 19

3.3.6. Avoiding overstatement ....... 19

3.3.7. Adapting words to the reader ...... 20

3.3.8. Never barbarous (advisory only) ..... 20

3.4. NON SEXIST LANGUAGE..... 20

3.5. WRITER’S BLOCK...... 21

3.5.1. Preparation..... 21

3.5.2. Make a start ........ 22

3.5.3. Review the reference material ..... 22

3.6. ENVIRONMENT ..... 22

3.7. ROUTINE ...... 22

3.8. ERGONOMICS ....... 23

3.8.1. Chair....... 23

3.8.2. Screen ..... 23

3.8.3. Regular breaks ........ 23

3.8.4. Keyboard ........ 23

4. THE FIRST DRAFT...... 25

4.1. BACKUPS...... 25

4.2. DECIDING ON THE REQUIRED USER DOCUMENTS ..... 25

4.3. USER DOCUMENT INCLUSION REQUIREMENTS ..... 26

4.4. USER DOCUMENT CONTENT REQUIREMENTS ... 27

4.4.1. Title page ........ 27

4.4.2. Inside page...... 27

4.4.3. Table of contents ..... 28

4.4.3.1. Comprehensive table of contents.......28

4.4.3.2. Simple table of contents....29

4.4.4. List of Illustrations ...... 29

4.4.5. Headers/footers....... 29

4.4.6. Document Introduction.... 29

4.4.6.1. Audience description ........30

4.4.6.2. Applicability statement .....30

4.4.6.3. Purpose statement.....30

4.4.6.4. Document usage description .....30

4.4.6.5. Related documents........30

4.4.6.6. Conventions......31

4.4.6.7. Problem solving instructions.....31

4.4.7. Body of document........ 31

4.4.7.1. Body of instructional documents .......32

4.4.7.2. Body of reference documents ....33

4.4.8. Error messages, known problems & error recovery...... 34

4.4.9. Appendixes...... 35

4.4.10. Bibliography ....... 35

4.4.11. Glossary...... 35

4.4.12. Index....... 36

4.4.13. User documentation presentation requirements... 36

4.4.13.1. Consistency ......36

4.4.13.2. Terminology .....36

4.4.13.3. Referencing related material .....36

4.4.14. Change control ....... 37

4.4.14.1. This-version function changes.......37

4.4.14.2. Next-version function changes ......37

5. DOCUMENT PRODUCTION ...... 38

5.1. DOCUMENT ORIENTATION..... 38

5.2. DOCUMENT ORGANISATION....... 38

5.3. DOCUMENT FORMAT..... 38

5.3.1. Double sided ....... 38

5.3.2. Table of contents ..... 39

5.3.3. Page size and margins..... 39

5.3.4. Headings..... 40

5.3.5. Body text ..... 40

5.3.6. Bullets..... 40

5.3.7. Representing screens....... 41

5.3.7.1. Overview......41

5.3.7.2. Screen capture techniques.....41

5.3.7.3. Screen requirements .....42

5.3.8. Keyboard function keys ....... 42

5.3.9. Numbered lists ........ 43

5.3.10. Figures & numerals..... 43

5.3.11. Justification ........ 43

5.3.12. Italics...... 43

5.3.13. Emphasis..... 43

5.3.14. Hyphenation........ 43

5.3.15. Acronyms & jargon ..... 44

5.3.16. Widow/orphan protection .... 44

5.3.17. Paragraph numbering ..... 44

5.3.18. Other considerations....... 44

6. EDITING & PROOF-READING...... 45

6.1. EDITING....... 45

6.1.1. Print first draft ........ 45

6.1.2. Bind ........ 45

6.1.3. Edit first draft ..... 45

6.1.4. Edit second draft ..... 46

6.1.5. Spell/grammar check, TOC, index ....... 46

6.1.6. First proof....... 47

6.1.7. Checklist ..... 47

6.2. PROOF-READING....... 48

6.2.1. Who proof-reads?........ 48

6.2.2. Deadlines ........ 49

6.2.2.1. Make the changes .....49

7. REVIEWING AND FIELD TESTING ..... 50

7.1. REVIEWING THE MANUAL ...... 50

7.1.1. Selecting reviewers and when to review... 50

7.1.2. Show reviewers how to review ..... 51

7.1.3. Give feedback to reviewers...... 52

7.2. FIELD TESTING THE MANUAL ..... 52

7.2.1. Selecting testers and when to test .... 52

7.2.2. Show testers how to test....... 52

7.2.3. Give feedback to testers....... 53

8. PRODUCTION...... 54

8.1. PAPER SIZE & WEIGHT....... 54

8.2. PRINT QUALITY..... 54

8.3. BINDING....... 54

8.4. DRILLING ..... 55

8.5. TAB DIVIDERS....... 55

8.6. REGISTRATION ..... 55

8.7. IDENTIFICATION OF CHANGES .... 56

8.8. DOCUMENT RELEASE ........ 56

8.9. VERSION CONTROL & RE-ISSUE OF DOCUMENTS ..... 57

8.10. CONTROLLED DISTRIBUTION DOCUMENTS...... 57

9. ON-LINE DOCUMENTATION.... 58

9.1. CONVERSION TO ON-LINE...... 58

9.2. CREATE THE PAPER MANUAL FIRST .... 59

10. MAINTENANCE....... 60

10.1. WHEN TO MAINTAIN ..... 60

10.2. PROCEDURE...... 60

10.3. CHANGE CONTROL........ 60

10.3.1. Post-publication software changes ...... 61

10.3.2. Post-publication document changes .... 61

11. GLOSSARY OF COMPUTER TERMS... 62

12. APPENDIX A - FORMS.... 84