1. Chapter 12 Writing for End Users
IFS410 End User Support
Chapter 12
Writing for End Users

2. Technical Writing
Documentation is written communication intended to provide support information to end users
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

3. Types of User Documents
Brochures and flyers
Newsletters
Handouts and training aids
User guides and manuals
Online help systems
and chat messages
Web pages
Proposals, letters, and memos
Procedural and operational documentation
Troubleshooting guides

4. Technical Writing Differs from Other Writing
Differences in
Writing style
Type of information communicated
Organization of document
Goals

5. Technical Writing Characteristics
Uses an economical writing style
Short, simple, declarative sentences, phrases, lists
Communicates information vital to a reader’s productivity (just the facts)
Uses a style and format that helps readers understand a sequence of events
Helps reader with transitions among topics
Is brief, but not cryptic (user productivity is goal)
Can contain pointers and cross-references
A pointer is reference to a location where a reader can locate more information on a topic
Use graphical examples to convey concepts.

6. 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

7. Common Organization for Technical Documents
Introduction
Purpose of document
Who document is intended for
Why read the document
Body
General explanation
Specific task steps
Common problems users encounter
Summary
Pointers to additional information

8. Document Planning Who is the target audience?
What does the audience already know?
What does the audience need to know?
What should the audience to be able to do when they finish reading the document? (What’s the goal)
How will the document be transmitted to the audience?

9. Help the Audience Most word processors include a readability index
Target the reading level at 8th or 9th grade
Most word processors include a readability index
Tell the reader who the intended audience is
Organize material so experienced reader can skip basic materials
State the purpose of a document in the first few sentences
Tell users what tasks they will be able to perform after completing the document
Tailor a document to the media
Printed: generally longer; help the reader with transitions
Online: generally shorter; help the reader with pointers

10. 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

11. 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
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

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

13. Clutter to illustrate a point not just for decoration
Use graphics
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
Avoid centered and block-justified
Justified text is aligned at both the right and left margins

14. 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

15. 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
Can you think of others?

16. 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 Pavilion 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 Pavilion PC, Excel, or the voice recognition utility? Or the user?

17. 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
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

18. Nominalization
Nominalization is the use of -tion an -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.

19. 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...
Use short words when possible
Use use instead of utilize
Use document instead of documentation
Use added instead of additional
Can you think of other examples?

20. Jargon
Jargon words are understood only by those experienced in a field
Use simple, direct words that anyone can understand
Example:
Avoid: Hack the document for the new NIC cards
Use: Edit the document for the new network cards
If you must use jargon terms, define them first

21. Undefined Acronyms
An acronym is a series of letter 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)

22. 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