Chapter 3 Writing for End Users A Guide to Computer User Support for Help Desk & Support Specialists Fourth Edition by Fred Beisse Chapter 3 Writing for End Users Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Outline Technical Writing Types of end-user documentation How technical writing differs from other writing How technical documents are organized How to plan effective user documents The technical writing process Strategies for technical writing Common problems in technical writing Tools used for technical writing How to evaluate documents Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Technical Writing Documentation: Written communication to provide information to end users Goal of technical writing: to produce documents that effectively and efficiently communicate information that readers need Effectively: Readers get correct information to master a topic or perform a task Efficiently: Readers do not have to waste time searching for information It’s all about the person you are writing to and for! Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Types of End User Documentation Brochures and flyers Webpages Newsletters Proposals, letters, and memos Handouts and training aids Procedural and operational documents User guides and manuals Troubleshooting guides Online help systems Email, chat, and text messages Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Brochures and Flyers Purpose: primarily for advertisement of: Staff training sessions Computer fairs Career fairs Product demonstrations Guest speakers Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Newsletters Purpose: communicate information Popular in large companies where support staff does not regularly contact other workers Formats: Printed Electronic distribution Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Handouts and Training Aids Purpose: summarize and promote recall of material covered in training session Example: printouts of PowerPoint slides Usually short and address a single topic Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

User Guides, Handbooks, and Manuals Purpose: supplement vendor documents with information specific to an organization or computer facility Formal Structure: Tutorial format: a step-by-step guide to hardware or software features in learning sequence (convenient for new users) Reference format: all material on each topic is covered in a single location (useful for experienced users) Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Online Help Systems Purpose: Common in software packages Features: Provide self training Common in software packages Features: Information presented must be brief Keyword searches , indexes and Hyperlinks provide powerful tools to locate information quickly Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Email, Chat, and Text Messages Purpose: formal and informal online communication With internal end users ( Client) , external end users (Coworkers) and vendors The primary method of communication for many support organizations Messages project an image of the organization and support specialist Should also use good technical writing skills Avoid the use of abbreviations (U, BTW, IMHO, etc.) Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Webpages Purpose: provide access to support materials on the web Need to be organized and written so users can locate information quickly and easily Must be short, but contain hypertext links to additional information Image of organization is projected in web documents An ongoing challenge is to keep web-based support information current and accurate Incorrect information is often worse than no information Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Proposals, Letters, and Memos Examples of business documents: Letters Needs Assessment Reports Proposal How much it costs, and how much it is worth, then further pages have tech details Memos Performance Appraisals Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Procedural and Operational Documents Purpose: procedure steps and checklists are primarily for internal use Can (and should) you put a checklist into the form of a document used to “prove” something was done correctly? Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Troubleshooting Guides Purpose: help support agents and computer users diagnose and solve problems Examples: Troubleshooting section in user manual FAQ on problems users encounter frequently Script on incident handling procedures Problem report in help desk knowledge base Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

How Technical Writing Differs from Other Writing Differences in: Goals Organization of document Type of information communicated Writing style Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Technical Writing Characteristics Uses simple sentences instead of compound ones Begins with the most important information first Communicates information vital to the reader’s productivity Describe a sequence of steps in the order performed Includes pointers and cross-references Focuses on information, not entertainment Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

How Technical Documents Are Organized Sequential organization: follows a step-by-step sequence from first to last Example: procedural check list for installation of hardware or software Hierarchical organization: flows from top to bottom, and from general to specific information Example: an online help system 1 2 3 general specific More specific Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Common Organization for Technical Documents Introduction Purpose of document Intended audience Why read document Body Specific task steps Common problems users encounter Summary Review of main points Pointers to additional information Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Document Planning Who is the target audience? Tell readers who the intended audience is What does the audience already know? If they don’t, where can they find it? Organize the document so experienced readers can skip basic materials Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Document Planning What does the audience need to know? State the document’s purpose in the first few sentences What do you want the audience to be able to do when they finish reading the document? Tell readers which tasks they can perform after completing the document What medium will be used to transmit the document to its audience? Printed: generally longer Online: generally shorter; help readers with pointers to additional information Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

The Technical Writing Process After documents writers have defined the audience , purpose , and medium for a document , they can begin to write the document it self. Generate a list of ideas or features Organize the list into a logical sequence (outline) Expand the outline into a first draft Edit the draft for clarity Arrange for an outside review Revise the draft into its final form Proofread the final document Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Step 1: Generate an Idea List Brainstorm: a technique to generate a list of potential topics as they think of that might be useful for the readers. During brainstorming, exclude nothing Major or minor After brainstorming , the idea list can be prioritized and reorganized. Some ideas will be major topics, others will become minor topics , and some will be discarded. Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Step 2: Organize the List into an Outline Once writers have a topic list that includes everything they want to cover, they arrange topics into a logical sequence Final organization should answer the following question: In what order does a reader need to know this information? Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Step 3: Expand the Outline into a First Draft After creating an initial outline and checking it for logical flow , a writer expands the outline into first draft by expanding each point in the outline. Strategies: Each paragraph has a topic sentence Use transitions between paragraphs and sections First . . ., Second . . ., Next . . ., Then . . ., Finally . . . Use numbers and bullet lists Define terms Format features Style elements Format consistency Lists and tables Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Step 4: Edit the Draft Pass 1: Eliminate extra words Pass 2: Perform a format consistency check Make sure that the fonts for headings and subheadings, indentation, centering, boldface, italics, and underlining are used consistently throughout a document. Tip: overuse of format features detracts from the document contents Pass 3: Perform a technical accuracy check Test procedural or technical steps Eliminate errors in instructions Check URLs for dead links Verify screenshots Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Step 5: Get an Outside Review Purpose: Identify and clarify any questions about contents Spot inconsistencies Find unclear meanings Identify poor writing techniques Locate other problems Tip: Sometimes a writer is too close to a document to see problems Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Step 6: Revise the Draft Incorporate revisions into a document Tip: When an edit pass results in marginal improvements, consider the document done Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Step 7: Proofread the Document Final pass through the document before publication Look for: Typos Inconsistent capitalization and punctuation Inconsistent font use Extra spaces between words and sentences Incorrect page breaks Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Technical Writing Strategies Analogy: comparing an unfamiliar concept with a familiar one Repetition Introduce Explain Summarize Consistent word use Use a consistent word to refer to each concept Avoid varying: DVD, DVD-ROM, digital video disc, optical disk Consistent verb tense Prefer present tense unless events clearly occurred in the past Introduce Explain Summarize Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Verb Tense – Example “After you have powered up your computer and booted into Windows, the network connection wizard is used to establish a network connection” “First, power up your computer and boot into Windows. Then use the network connection wizard to establish a network connection” Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Common Technical Writing Problems Clutter Inappropriate typefaces Gender references Unclear referents Passive voice Nominalization Wordiness Jargon Undefined acronyms Dangling phrases Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

1- Clutter Use graphics to illustrate (screenshot) or highlight a point but not for decoration Use formatting to help locate information or understand a topic Include considerable white space Use at least 10-point body text Left-align most body text Centered text and block-justified text are harder to rea زينة Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

2- Inappropriate Typefaces Use simple clear typefaces Save special typefaces for informal use Invitations, brochures, flyers Is this readable? Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

3- 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 Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

4- Unclear Referents Referent: a concrete word or concept that is designated (referred to) by another word The referent of words such as it, them, this, he, she and their should be clear. Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

5- Passive Voice Passive voice: the subject of the sentence receives the action. Avoid passive voice Active voice: the subject of the sentence performs the action indicated by the verb. Use active voice to make text livelier and more interesting The final report was submitted. The project team submits its final report. Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

6- Nominalization Perform an installation of the printer driver Nominalization: the use of - tion, -ing, -ment, and similar endings to create nouns where verbs are easier to understand Install the printer driver Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

7- Wordiness Avoid unnecessary words Use short words when possible Prior to the actual installation of the system Avoid unnecessary words Use short words when possible Before installing the system utilize use Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

8- Jargon Jargon: words understood primarily by those experienced in a field Use simple, direct words that anyone can understand If you use jargon terms, define them first Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

9- Undefined Acronyms RAM Acronym: a word formed from the initial letters of words in a phrase Random Access Memory Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

10- Dangling Modifier Needless to say, the installer should verify that the user’s PC is operational, of course. Dangling modifier: a word or phrase at the beginning or end of a sentence that adds little meaning The installer should verify that the user’s PC is operational. لا داعي لقوله غني عن القول Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Technical Writing Tools Spell checker Custom dictionary Thesaurus Grammar checker Desktop publishing features Help writer produce professional - looking document. Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)

Document Evaluation Criteria Content Format Is the information timely, relevant, complete and accurate? Does the layout help guide the reader? Organization Is the format consistent? Mechanics Is the information easy to locate? Can readers get in and out quickly with the answer they need? Are words spelled correctly? Is it grammatically correct? Created by L. Asma Rikli (adapted from A Guide to Computer User Support for Help Desk and Support Specialties by Fred Beisse)