1. CTS 217: Computer Training & Support
Chapter 11
Writing for End Users

2. Learning Objectives Types of end-user documentation
How technical writing differs from other writing
How technical documents are organized
How to plan effective user documentation
The technical writing process
Effective use of formats
Strategies for technical writing
Common problems in technical writing
Tools used in technical writing
How to evaluate documents

3. Technical Writing
Documentation is written communication intended to provide support information to end users
QR sheets, online assistants, FAQ, ReadMe files
Goal of technical writing: To produce documents that effectively and efficiently communicate information a reader needs
Effectively: Readers get the correct information they need to master a topic or perform a task
Efficiently: Readers do not have to spend extra time searching for information
Good technical writing saves users time

4. Types of User Documentation
Brochures and flyers
Web pages
Newsletters
Proposals, letters, & memos
Handouts and training aids
Procedural and operational documentation
User guides, h/b, and manuals
Troubleshooting guides
Online help systems
and chat msg

5. Brochures and Flyers Purpose: primarily promotional Used to advertise
Catch reader’s eye (Design!)
“Sell” event
Used to advertise
Staff training sessions
Open houses
Computer fairs
Hardware and software product demonstrations or availability
Guest speakers

6. Newsletters
Purpose: used by support groups to communicate with their users
Multiple columns, pics, diagrams, charts
Tips and tricks
Popular in large companies where support staff does not regularly come into direct contact with other workers
Can be printed or distributed electronically

7. Handouts and Training Aids
Purpose: summarize and promote recall of material covered in a training session
May be distributed online
FAQ (How do I…)
PowerPoint handouts in online courses
Usually short and address a single topic

8. User Guides, H/books, & Manuals
Purpose: supplement vendor documentation and trade books with information specific to an organization or computer facility
Handbook for computer use at a university
How to install and use products (QS guide)
Structure:
Tutorial format is a document organization style which guides a user step-by-step to hardware or software features
Reference format is a document organization style in which all material on a topic is in one location
Probably better for experienced users
Combination format – tutorial plus reference

9. Online Help Systems Purpose: Information presented must be concise
provide convenient access to information for users
replace or supplement printed materials
Information presented must be concise
Use of hypertext links and index searches provide powerful tools to locate needed information quickly
Troubleshooters in Windows
Increasing in popularity and convenience
Not all users are comfortable with online materials

10. E-mail and Chat Messages
Purpose: formal and information online communications
with external clients and vendors
with internal end users and work colleagues
Projects an image of the organization and support specialist
Should reflect good technical writing skills
Use correct grammar and spelling!!
Netiquette

11. Web Pages Purpose: make support materials available on the Internet
Need to be organized and written so that users can locate information quickly and easily
Too easy to visit another site
Must be very short, but contain hypertext links that lead users to additional information
Image of organization is at stake in Web documents
Challenge is to keep Web-based support information current and accurate
WorstOfTheWeb.com & Basic Design Site

12. Proposals, Letters, & Memos
Purpose: organizational correspondence accounts for a significant portion of computer use
Proposals
Letters
Memos
Needs assessment reports
Performance appraisals
Other correspondence
Ability to produce basic business correspondence is an important user support skill

13. Procedural and Operational Doc.
Purpose: written procedure steps and checklists intended primarily for internal organizational use (may enjoy this type of writing J)
Examples
Preparation of problem reports in a help desk environment
Documentation of hardware or software installation procedures
Unclear = wastes time, escalates frustration, hinders productivity

14. Troubleshooting Guides
Purpose: help end users solve computer problems
Examples
Problem-solving section in User Guide
FAQ on frequent problems users encounter
Script on incident handling procedures
Problem report in Help Desk knowledge base
Must be clear, concise, and well written
Next – look at differences in types of writing

15. How Technical Writing Differs from Other Writing
Differences in
Writing style
NOT a research paper
Type of information communicated
Goals
Style
Organization of document

16. Technical Writing Characteristics
Uses an economical writing style
Short, simple, declarative sentences, phrases, lists
Simple, compound, run-on sentences p. 499
NOT entertaining
Communicates most important point at beginning of topic
Uses a style and format that helps readers understand a sequence of events
Example 2 on p. 499

17. Technical Writing Characteristics
Is brief but not cryptic
Cover essentials clearly and effectively
Can contain pointers and cross-references
A pointer is reference to a location where a reader can locate more information on a topic
Goal: not to entertain, leave out humor and fancy words

18. How Technical Documents Are Organized
Sequential organization follows a step-by- step sequence from first to last
Example: procedural documentation for installation of hardware or software
Hierarchical organization flows from top to bottom, and from general information to specific information
Example: online help systems
Use combination

19. Common Org. for Tech Docs
Introduction
Purpose of document
Who document is intended for (audience)
Not waste time
Why read the document
Body
Gen inf; specific task steps
Include MAIN points only
Common problems users encounter
Summary
Review; additional information?

20. Document Planning Similar to those for training session
Who is the target audience?
Their level of expertise
Reading level: target 8th or 9th grade (readability stats)
What does the audience already know?
Their bkg; stmt in Intro; might skip your doc
Section headings for basics so exp. users can skip

21. Document Planning What does the audience need to know?
Define purpose of document
What should the audience to be able to do when they finish reading the document?
Specific task should be accomplished after they read it/follow steps
How will the document be transmitted to the audience?
Print? Online? Transitions, hyperlinks to guide

22. Steps in the Technical Writing Process
1. Generate an idea list 2. Organize the list into a logical outline 3. Expand the outline into a first draft 4. Edit the draft one or more times 5. Arrange for an outside review 6. Revise the draft into its final form 7. Proofread the document 8. Proofread the document AGAIN!

23. Step 1: Generate an Idea List
Brainstorm is a technique to generate a list of potential topics
Tip: During brainstorming, don’t worry about whether a topic is
major or minor
useful or not
high or low priority
After brainstorm: prioritize, reorganize, refine

24. Step 2: Organize the List Into an Outline
Arrange topics into logical sequence
Identify major and minor topics
Cut and paste to try out different sequences of ideas
Use a word processor’s outline feature as a tool
The final organization should answer the question:
In what order does the reader need to know this information?

25. Step 3: Expand Outline into 1st Draft
Paragraphs with topic sentences
Transitions between paragraphs and sections
As a result, for example, first, next, finally
Define terms
Bold face
Formats (Do not overdo it!!)
Style elements: fonts, capitalization, centering, indentation, underlines, bullets and numbered lists help a reader understand the structure
Format consistency: style sheets and templates in word processors help insure consistent use of style elements
Lists and tables: use instead of long narrative passages to help a reader locate information needed quickly

26. Step 4: Edit the Draft Eliminate extra words
Example on p. 507
Perform a format consistency check
Consistent use of fonts for headings, subheadings, centering, boldface, italics, and underlining
WP software helps with this
Perform a technical accuracy check
A test of any procedural or technical steps
Eliminates errors in instructions
Check URLs to eliminate dead links

27. Step 5: Get an Outside Review
Purpose:
Raise questions about contents
Spot inconsistencies
Find unclear meaning
Identify poor writing techniques
Locate other problems that the writer is too close to the document to see
Analogous to beta testing a training module
Don’t be defensive!

28. Step 6: Revise the Draft Incorporate revisions into document
When an edit pass results in marginal improvements, consider it done
Perfectionist? Know when to stop

29. Step 7: Proofread the Draft
Final pass through a document prior to publication
Look for
Inconsistent capitalization and punctuation
Inconsistent font use
Extra spaces between words and sentences
May show as grammar error in Word
Incorrect page breaks

30. Technical Writing Strategies
An analogy describes how an unfamiliar concept is similar to a familiar concept
Repetition
Introduce, explain, summarize
Consistent word use
Use the same word to refer to a concept
NOT worried about variety (synonyms)
Avoid mixing: CD, CD-ROM, compact disc, optical disk
Style sheet lists preferences for spelling and word use
Example: End user is a noun; End-user is an adjective
Consistent verb tense
Prefer present tense unless an event clearly occurred in the past (p. 512)

31. Sample Page from a Style Sheet

32. Technical Writing Strategies (cont.)
Parallel structure treats similar items consistently throughout a document.
Titles, headings, subheadings
Verb tenses and parts of speech
Bulleted lists

33. Common Problems in Technical Writing
Clutter
Nominalization
Inappropriate typefaces
Wordiness
Jargon
Gender references
Undefined acronyms
Dangling phrases
Unclear referents
Passive voice

34. CLUTTER Use graphics Use formatting Include considerable white space
to illustrate a point
not just for decoration
Use formatting
sparingly and consistently
only when it helps locate information or understand topic
Include considerable white space
Use at least 9 point body text
Larger for slide shows, brochures, flyers
Left align most body text (easiest to read)
Avoid centered and block-justified
Justified text is aligned at both the right and left margins.

35. Inappropriate Typefaces
Serif typeface includes fine lines (serifs) that project from the top and bottom of a font’s characters
frequently used for body text
Sans serif typeface does not have serifs
often used for titles and headings
Specialty typeface is a style of type intended for special use to draw attention to text
save for informal use

36. Example Typefaces Which is most readable?

37. Gender References Avoid gender-related words unless they clearly fit
Avoid: he, she, him, her, s/he
Use: they, their, it, he and she, she and he
Gender-neutral words are clearer and less offensive
Use staffed instead of manned
Use chair instead of chairman
Use supervisor instead of foreman

38. Unclear Referents
Referent is a word that refers to another word or concept
The referent of words such as it, them, and their should be clear
Example: The user was using Excel on her HP DC7900 PC to enter a long list of numbers with her voice recognition utility program. Half-way through the list, it froze up.
Does it refer to the HP PC, Excel, or the voice recognition utility?

39. Passive Voice
Active voice is a sentence in which the subject performs the action indicated by the verb
Example: I prepared the documentation.
Use active voice to make text livelier and more interesting
Table 11-1 on p. 516
Passive voice is a sentence in which the subject receives the action indicate by the verb
Example: The documentation was prepared by me.
Avoid passive voice

40. Nominalization
Nominalization is the use of -tion and -ing endings to create nouns where verbs are easier to understand
Example
Use of nominalization: Perform an installation of the printer driver.
Use of verb: Install the printer driver.
Table 11-2 on p. 517

41. Wordiness Avoid unnecessary words Use short words when possible
Too many words: Prior to the actual installation of the system...
Reduced: Before installing the system...
Table 11-3 on p. 517
Use short words when possible
Use use instead of utilize
Use document instead of documentation
Use added instead of additional

42. Jargon
Jargon words are understood only by those experienced in a field
Use simple, direct words that anyone can understand
Examples:
Avoid: Hack the document for the new NIC cards
Use: Edit the document for the new network cards
Start-up process = power-on step
If you must use jargon terms, define them first

43. Undefined Acronyms
An acronym is a series of letters that represent a phrase
Example: RAM is a acronym for random access memory
Define the meaning of acronyms for the reader
The first time acronym is used, spell out the words then include the acronym in parentheses
Example: digital video disc (DVD)
Include acronyms in a glossary
Tip: Don’t create unnecessary new acronyms
Example: Technical Writers Against Unnecessary Acronym Use (TWAUAU)

44. Dangling Phrases
A dangling phrase is a word or phrase at the beginning or end of a sentence that adds little meaning
Example: The installer will verify that the user’s PC is operational, of course.
Avoid a word (or phrase) at the beginning or end of a sentence that adds little meaning to the sentence
Eliminate the word (or phrase) or include it elsewhere in the sentence
Examples & web site on p

45. Technical Writing Tools
Read critically. What
makes it good or bad?
Outline tool
Spell checker
Custom dictionary
Thesaurus
Grammar checker
Readability index
Desktop publishing features
Collegiate dictionary (m-w.com)

46. Document Evaluation Criteria
Content
Format
Relevant, accurate information
Layout guide reader
Consistent format
Complete coverage of topic
Mechanics
Spelling
Organization
Grammar
Easy to locate info
Effective writing style
Clear transitions
Find answers quickly

47. Chapter Summary
User support staff write a variety of different types of documents to communicate with end users, coworkers, vendors, and managers
The goal of technical documents is to effectively and efficiently communicate information needed by the reader
Technical writing begins by defining the characteristics of the target audience and the task the writer wants the reader to be able to do
Technical writing uses short words and sentences and an organization that helps the reader locate information

48. Chapter Summary (continued)
The technical writing process includes
1. Generate an idea list
2. Organize the list into a logical outline
3. Expand the outline into a first draft
4. Edit the draft one or more times
5. Arrange for an outside review
6. Revise the draft into its final form
7. Proofread the document
The layout of a document and formatting help the reader to understand the organization and transitions between topics
Successful writers use analogies, repetition, consistent work use and parallel structure

49. Chapter Summary (continued)
Successful writers avoid clutter, hard-to-read typefaces, gender references, passive voice, unclear referents, wordiness, jargon, and acronyms
Software tools that aid writers include an outliner, spell checker, thesaurus and grammar checker
Four criteria to evaluate technical documents are
Content
Organization
Format
Mechanics