chapter 12 writing for end users. guide to computer user support, 3e 2 types of end-user...

Chapter 12

Writing for End Users

Guide to Computer User Support, 3e 2

• 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

Learning Objectives


• 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

Technical Writing


• Brochures and flyers

• Newsletters

• Handouts and training aids

• User guides and manuals

• Online help systems

• E-mail and chat messages

• Web pages

• Proposals, letters, and memos

• Procedural and operational documentation

• Troubleshooting guides

Types of User Documents


• 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

Brochures and Flyers


• 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

Newsletters


• Purpose: summarize and promote recall of material covered in a training session

• May be distributed online

• Usually short and address a single topic

Handouts and Training Aids


• 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

User Guides, Handbooks, and Manuals


• 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

Online Help Systems


• 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

E-mail and Chat Messages


• 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

Web Pages


• 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

Proposals, Letters, and Memos


• 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)

Procedural and Operational Documentation


• 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

Troubleshooting Guides


• Differences in

• Writing style

• Type of information communicated

• Organization of document

• Goals

How Technical Writing Differs from Other Writing


• 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

Technical Writing Characteristics


• 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

How Technical Documents Are Organized


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


• 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?

Document Planning


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


1. Generate an idea list2. Organize the list into a logical outline3. Expand the outline into a first draft4. Edit the draft one or more times5. Arrange for an outside review6. Revise the draft into its final form7. Proofread the document

Steps in the Technical Writing Process


Step One: Generate an Idea ListStep 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


• 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?

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

Step Two: Organize the Idea List into an Outline


• 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

Step Four: Edit the Draft


• 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

Step Five: Get an Outside Review


• Incorporate revisions into document

• When an edit pass results in marginal improvements, consider it done

Step Six: Revise 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

Step Seven: Proofread the Draft


• 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

Technical Writing Strategies


Sample Page from a Style Sheet


Technical Writing Strategies (continued): Parallel Structure

• Parallel structure treats similar items consistently throughout a document.• Parallel structure treats similar items consistently throughout a document.


• Clutter

• Inappropriate typefaces

• Gender references

• Unclear referents

• Passive voice

• Nominalization

• Wordiness

• Jargon

• Undefined acronyms

• Dangling phrases

Common Problemsin Technical Writing


• 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

Justified text is aligned at both the right and left margins

Clutter


• 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

Inappropriate Typefaces


Example TypefacesWhich is most readable?


• 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?

Gender References


• 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?

Unclear Referents


• 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

Passive Voice


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

Nominalization


• Avoid unnecessary words• 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?

Wordiness


• 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

Jargon


• 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)

Undefined Acronyms


• 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

Dangling Phrases


• Outliner

• Spell checker

• Custom dictionary

• Thesaurus

• Grammar checker

• Readability index

• Desktop publishing features

• Collegiate dictionary

Technical Writing Tools


• Content

• Organization

• Format

• Mechanics

Document Evaluation Criteria (Overview)


• Is the information accurate?

• Is the coverage of the topic complete?

Content


• Is the information easy to locate?

• Are the transitions between topics identifiable?

• Can the user get in and out quickly with the right answer?

Organization


• Does the layout help guide the reader?

• Is the format consistent?

Format


• Are words spelled correctly?

• Is it grammatical?

• Is the writing style effective?

Mechanics


• 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

Chapter Summary


Chapter Summary (continued)

• The technical writing process includes1. Generate an idea list2. Organize the list into a logical outline3. Expand the outline into a first draft4. Edit the draft one or more times5. Arrange for an outside review6. Revise the draft into its final form7. 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


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

chapter 12 writing for end users. guide to computer user support, 3e 2 types of end-user...

Documents

computer user support

support information

technical writing tools

user stepbystep

support staff

effective user documentation

technical documents

support specialist