Chapter 12 Chapter 12: Writing for End Users A Guide to Computer User Support for Help Desk and Support Specialists second edition by Fred Beisse

Chapter 12 Learning Objectives n Types of end user documentation n How technical writing differs from other writing n How technical documents are organized n Plan effective documentation n The technical writing process n Use formats effectively n Technical writing strategies n Common problems in technical writing n Tools used in technical writing n Evaluate documentation

Chapter 12 Technical Writing n Goal: To produce documentation that effectively and efficiently communicates information the reader needs u Effectively: Readers get the correct information they need to master a topic or perform a task u Efficiently: Readers do not have to spend extra time searching for information n Good documentation saves users time

Chapter 12 Types of User Documentation n Brochures and flyers n Newsletters n Handouts and training aids n User guides and manuals n Online help systems n messages n Web pages n Proposals, letters, and memos n Procedural documentation n Troubleshooting guides

Chapter 12 Brochures and Flyers n Purpose: Primarily promotional u Intended to catch the eye of the reader and sell an event n Used to advertise u Staff training sessions u Open houses u Computer fairs u Product demonstrations or availability u Guest speakers

Chapter 12 Newsletters n Purpose: Used by user support groups to communicate with their users n Popular in large companies where support staff does not regularly come into direct contact with other employees n Can be printed or distributed electronically

Chapter 12 Handouts and Training Aids n Purpose: Summarize and promote recall of material covered in a training session n May be distributed online n Usually short and address a single topic

Chapter 12 User Guides, Handbooks, and Manuals n Examples of more formal pieces of written documentation n Purpose: Supplement vendor documentation and trade books with information specific to a company or computer facility n Organization: u Tutorial format – step-by-step guide to features u Reference format – all material on a topic in one location u Combination format – tutorial plus reference

Chapter 12 Online Help Systems n Purpose: u provide convenient access to information for computer users u Replace or supplement printed materials n Information presented must be succinct n Use of hypertext links and index searches provide powerful tools to locate needed information quickly n Increasing in popularity and convenience n Not all users are comfortable with online materials

Chapter 12 Messages n Purpose: formal and information online communications u External with clients and vendors u Internal with end users and colleagues n Project an image of the organization and support specialist n Should reflect good technical writing skills n Emphasizes need for excellent writing skills for user support specialists

Chapter 12 Web Pages n Purpose: an increasing amount of support materials is being made available on the Web n Needs to be organized and written so that users can locate information quickly and easily n Must be very short, but contain hypertext links that lead users to additional information n Image of company is at stake in Web documents

Chapter 12 Proposals, Letters, and Memos n Purpose: organizational correspondence accounts for a significant portion of computer use u Proposals u Letters u Memos u Needs assessment reports u Performance appraisals u Other correspondence n Ability to produce basic business corres- pondence is an important user support skill

Chapter 12 Procedural and Operational Documentation n Purpose: written procedure steps and checklists intended primarily for internal company use n Preparation of problem reports in a help desk environment

Chapter 12 Troubleshooting Guides n Purpose: Help end users solve problems n Examples u Chapter on problem-solving u FAQ on frequent problems users encounter u Script on call handling procedures u Problem report in HD knowledge base n Must be clear, concise, and well written

Chapter 12 How Technical Writing Differs from Other Writing n Differences in u Style u Type of information it communicates u Organization u Goals

Chapter 12 Technical Writing n Uses an economical writing style n Communicates information vital to reader’s productivity n Uses a style and format that helps readers understand sequence of events n Is brief, but not cryptic n Can contain pointers and cross- references

Chapter 12 How Technical Documents Are Organized n Sequential organization – step-by-step, from first to last u Example: procedural documentation n Hierarchical organization – from top to bottom, and from general to specific u Example: online help systems

Chapter 12 Common organization for technical documents n Introduction u Purpose of document u Who document is intended for u Why read the document n Body u General explanation u Specific task steps u Common problems users encounter n Summary u Pointers to additional information

Chapter 12 Documentation Planning n Who is the target audience? n What does the audience already know? n What does the audience need to know? n What do you want the audience to be able to do when they finish reading your document?

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

Chapter 12 Step 1: Generate an Idea List n Brainstorm to generate a list of potential topics n Tip: Don’t worry about whether a topic is major or minor, or its priority

Chapter 12 Step 2: Organize the List into an Outline n Organize topics into logical sequence n Cut and paste to try out different sequence of ideas n The final organization should answer the question: F In what order does reader need to know this information?

Chapter 12 Step 3: Expand the Outline into a First Draft n Paragraphs with topic sentences n Transitions n Defined terms n Formats

Chapter 12 Step 4: Edit the Draft n Eliminate extraneous words n Perform a format consistency check F Consistent use of fonts for headings, subheadings, centering, boldface, italics, and underlining n Perform a technical accuracy check F Eliminate errors in instructions

Chapter 12 Step 5: Get an Outside Review n Purpose: u Raise questions u Spot inconsistencies u Find unclear meaning u Identify poor writing techniques u Locate other problems that the writer is too close to see

Chapter 12 Step 6: Revise the Draft n Incorporate revisions n When an edit pass results in marginal improvements, consider it done

Chapter 12 Step 7: Proofread the Draft n Look for u Inconsistent capitalization and punctuation u Inconsistent font use u Extra spaces between words and sentences u Incorrect page breaks

Chapter 12 Technical Writing Strategies n Analogies n Repetition n Consistent word use u Style sheet – preferences for spelling and word use n Parallel structure n Consistent verb tense

Chapter 12 Sample Page from a Style Sheet

Chapter 12 Common Problems in Technical Writing n Clutter (unnecessary graphics) n Inappropriate typefaces n Gender references n Unclear referents (it, them, their) n Passive voice n Nominalization (Avoid the use of -tion an -ing endings) u Installation versus Install n Wordiness n Jargon (IT Terms) n Undefined acronyms n Dangling phrases

Chapter 12 Clutter n Use graphics to illustrate a point, not just for decoration n Use formatting sparingly and consistently, and only when it helps locate information or understand subject n Include considerable white space n Use at least 9 point body text n Left align most body text

Chapter 12 Inappropriate Typefaces n Sans serif typefaces are often used for titles and headings n Serif typefaces are frequently used for body text n Save specialty typefaces for informal use

Chapter 12 Gender References n Avoid gender-related words unless they clearly fit n Gender-neutral words are clearer and less offensive

Chapter 12 Unclear Referents n Referent: A word that refers to another word or concept n The referent of words such as it, them, and their should be clear

Chapter 12 Passive Voice n Use active voice to make text livelier and more interesting n Example u Passive: “The documentation was prepared by me.” u Active: “I prepared the documentation.”

Chapter 12 Nominalization n Avoid the use of -tion an -ing endings to create nouns where verbs are easier to understand n Example u Use of nominalization: “Perform an installation of the printer driver.” u Use of verb: “Install the printer driver.”

Chapter 12 Wordiness n Avoid unnecessary words u Too many words: “Prior to the actual installation of the system...” u Reduced: “Before installing the system...” n Use short words when possible u Long word: “Utilize” u Short word: “Use”

Chapter 12 Jargon n Use simple, direct words that anyone can understand n Example: u Hack the document for the new NIC cards u Edit the document for the new network cards n If you must use jargon terms, define them first

Chapter 12 Undefined Acronyms n Define the meaning of acronyms for the reader n First time acronym is used, spell out the words then include the acronym in parentheses u Example: digital video disc (DVD) n Include acronyms in a glossary n Tip: Don’t create unnecessary new acronyms u Example: Technical Writers Against Unnecessary Acronym Use (TWAUAU)

Chapter 12 Dangling Phrases n Avoid a word (or phrase) at the beginning or end of a sentence that adds little meaning to the sentence n Eliminate the word (or phrase) or include it in the sentence

Chapter 12 Technical Writing Tools n Outliner n Spell checker n Thesaurus n Grammar checker n Readability index n Desktop publishing features n Dictionary

Chapter 12 Documentation Evaluation Criteria n Content n Organization n Format n Mechanics

Chapter 12 Content n Is the information accurate? n Is the coverage of the topic complete?

Chapter 12 Organization n Is the information easy to locate? n Are the transitions between topics identifiable? n Can the user get in and out quickly with the right answer?

Chapter 12 Format n Does the layout help guide the reader? n Is the format consistent?

Chapter 12 Mechanics n Are words spelled correctly? n Is it grammatical? n Is the writing style effective?