End User Support – User Training Documentation for End Users

Objectives Types of Documentation Technical Writing Organisation of Technical Documents Document Planning Process and Strategies Problems with Technical Writing Tools Evaluation Criteria

Documentation for End Users Training can be a once-off session These sessions can be split over a number of days or weeks It is therefore important that the trainee can take something back to the work place in order to remind themselves of their training.

Types of Documentation Brochures and Flyers Proposals, Letters and Memos Newsletters Handouts and Training Aids E-mail Messages Procedural Documentation Web Pages User Guides and Manuals On-line Help Troubleshooting Guides

Technical Writing Technical writing differs from other types of writing because of the following factors: Style Information Goals Uses short phrases, short sentences, lists

Technical Writing Communicates a step-by-step sequence of events or tasks Important points should remain at the beginning It should be brief but not lacking information essential to understanding Uses an economical writing style to present information

Organisation of Technical Documents Introduction Purpose Who is it for Why read it Body Explain the Tasks and Steps Common problems users encounter More detailed information Summary Pointers to additional information

Document Planning Who is it for? What do they already know? What do they need to know? How will they use the documentation? What do you want them to be able to do when they have finished reading the document?

The Process Generate a List of Ideas or features to be covered Organise the list into a logical sequence to form an outline Expand the outline into a first draft Edit as required Review Externally Revise into Final form Proof-read the Document

Strategies Analogies Repetition Consistent Word Use Parallel Structure Similar items are handled consistently Consistent verb tense

Problems with Technical Writing Clutter Nominalisation (use of –tion and –ing endings to create nouns; verbs are easier to understand) Inappropriate Typefaces Wordiness Gender References

Problems with Technical Writing Jargon / undefined acronyms Passive Voice Unclear References Dangling Phrases A few words (or single word) at the beginning or end of a sentence that add little to the meaning of the sentence other than making it longer

Technical Writing Tools Word processing functions technical writers can use: Outliner Spell Checker Grammar Checker Thesaurus Readability Index Desktop Publishing Specialist tools (include programming capability)

Evaluation Criteria Content Organisation Is it accurate? Is the coverage of the topic complete? Organisation Is the information easy to locate? Are the transitions between topics identifiable? Can the user get in and out quickly with the right answer?

Evaluation Criteria Format Mechanics Does the layout help the reader? Is the format consistent? Mechanics Are the words spelled correctly? Is the grammar correct? (incl. correct homophones used) Is the writing style effective?

In Conclusion Types of Documentation Technical Writing Organisation of Technical Documents Document Planning Process and Strategies Problems with Technical Writing Tools Evaluation Criteria