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

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

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

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 E-mail and chat msg

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

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

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

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

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

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 http://owl.english.purdue.edu/owl/resource/636/01

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

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

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

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

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

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

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

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

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?

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

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

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!

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

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?

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

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

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!

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

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

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)

Sample Page from a Style Sheet

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

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

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.

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

Example Typefaces Which is most readable?

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

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?

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

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

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

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

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)

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. 518-519

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)

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

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

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

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