Download presentation
Presentation is loading. Please wait.
1
Chapter 12 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 Technical writing strategies Common problems in technical writing Tools used in technical writing How to evaluate documents Guide to Computer User Support, 3e
3
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 Guide to Computer User Support, 3e
4
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 Guide to Computer User Support, 3e
5
Brochures and Flyers Purpose: primarily promotional
Intended to catch the eye of the reader and sell an event Used to advertise Staff training sessions Open houses Computer fairs Product demonstrations or availability Guest speakers Guide to Computer User Support, 3e
6
Newsletters Purpose: used by support groups to communicate with their users Popular in large companies where support staff does not regularly come into direct contact with other workers Can be printed or distributed electronically Guide to Computer User Support, 3e
7
Handouts and Training Aids
Purpose: summarize and promote recall of material covered in a training session May be distributed online Usually short and address a single topic Guide to Computer User Support, 3e
8
User Guides, Handbooks, and Manuals
Purpose: supplement vendor documentation and trade books with information specific to an organization or computer facility 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 Combination format – tutorial plus reference Guide to Computer User Support, 3e
9
Online Help Systems Purpose:
provide convenient access to information for users replace or supplement printed materials Information presented must be succinct Use of hypertext links and index searches provide powerful tools to locate needed information quickly Increasing in popularity and convenience Not all users are comfortable with online materials Guide to Computer User Support, 3e
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 Growth in use of these communications emphasizes the need for excellent writing skills for user support specialists Guide to Computer User Support, 3e
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 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 Guide to Computer User Support, 3e
12
Proposals, Letters, and 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 Guide to Computer User Support, 3e
13
Procedural and Operational Documentation
Purpose: written procedure steps and checklists intended primarily for internal organizational use Examples Preparation of problem reports in a help desk environment Documentation of hardware or software installation procedures Site Management Notebook (see chapter 10) Guide to Computer User Support, 3e
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 Guide to Computer User Support, 3e
15
How Technical Writing Differs from Other Writing
Differences in Writing style Type of information communicated Organization of document Goals Guide to Computer User Support, 3e
16
Technical Writing Characteristics
Uses an economical writing style Short, simple, declarative sentences, phrases, lists Communicates information vital to a reader’s productivity Uses a style and format that helps readers understand a sequence of events Helps reader with transitions among topics Is brief, but not cryptic Can contain pointers and cross-references A pointer is reference to a location where a reader can locate more information on a topic Guide to Computer User Support, 3e
17
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 Guide to Computer User Support, 3e
18
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 Guide to Computer User Support, 3e
19
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? How will the document be transmitted to the audience? Guide to Computer User Support, 3e
20
Help the Audience 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 Guide to Computer User Support, 3e
21
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 Guide to Computer User Support, 3e
22
Step One: 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 Guide to Computer User Support, 3e
23
Step Two: Organize the Idea List Into an Outline
Arrange topics into logical sequence Identify major and minor topics Cut and paste to try out different sequence 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? Guide to Computer User Support, 3e
24
Step Two: Organize the Idea List into an Outline
Paragraphs with topic sentences Transitions between paragraphs and sections Define terms Formats 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 Guide to Computer User Support, 3e
25
Step Four: Edit the Draft
Eliminate extra words Perform a format consistency check Consistent use of fonts for headings, subheadings, centering, boldface, italics, and underlining Perform a technical accuracy check A test of any procedural or technical steps Eliminates errors in instructions Check URLs to eliminate dead links Guide to Computer User Support, 3e
26
Step Five: 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 Guide to Computer User Support, 3e
27
Step Six: Revise the Draft
Incorporate revisions into document When an edit pass results in marginal improvements, consider it done Guide to Computer User Support, 3e
28
Step Seven: 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 Incorrect page breaks Guide to Computer User Support, 3e
29
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 Guide to Computer User Support, 3e
30
Sample Page from a Style Sheet
Guide to Computer User Support, 3e
31
Technical Writing Strategies (continued): Parallel Structure
Parallel structure treats similar items consistently throughout a document. Guide to Computer User Support, 3e
32
Common Problems in Technical Writing
Clutter Inappropriate typefaces Gender references Unclear referents Passive voice Nominalization Wordiness Jargon Undefined acronyms Dangling phrases Guide to Computer User Support, 3e
33
Clutter 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 Guide to Computer User Support, 3e
34
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 Guide to Computer User Support, 3e
35
Example Typefaces Which is most readable?
Guide to Computer User Support, 3e
36
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? Guide to Computer User Support, 3e
37
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? Guide to Computer User Support, 3e
38
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 Guide to Computer User Support, 3e
39
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. Guide to Computer User Support, 3e
40
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? Guide to Computer User Support, 3e
41
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 Guide to Computer User Support, 3e
42
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) Guide to Computer User Support, 3e
43
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 Guide to Computer User Support, 3e
44
Technical Writing Tools
Outliner Spell checker Custom dictionary Thesaurus Grammar checker Readability index Desktop publishing features Collegiate dictionary Guide to Computer User Support, 3e
45
Document Evaluation Criteria (Overview)
Content Organization Format Mechanics Guide to Computer User Support, 3e
46
Content Is the information accurate?
Is the coverage of the topic complete? Guide to Computer User Support, 3e
47
Organization Is the information easy to locate?
Are the transitions between topics identifiable? Can the user get in and out quickly with the right answer? Guide to Computer User Support, 3e
48
Format Does the layout help guide the reader?
Is the format consistent? Guide to Computer User Support, 3e
49
Mechanics Are words spelled correctly? Is it grammatical?
Is the writing style effective? Guide to Computer User Support, 3e
50
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 Guide to Computer User Support, 3e
51
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 Guide to Computer User Support, 3e
52
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 Guide to Computer User Support, 3e
Similar presentations
