1. A Guide to Computer User Support for Help Desk & Support Specialists Fourth Edition by Fred Beisse Chapter 11 Writing for End Users

2. Chapter Objectives In this chapter, students will learn about: 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 A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 2

3. Documentation: written communication to provide user support information to end users Goal of technical writing: to produce documents that effectively and efficiently communicate information reader’s 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 Good technical writing saves users time Technical Writing A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 3

4. 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 A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 4

5. Purpose: primarily promotional –Catch the eye of the reader and sell an event Use: advertise: –Staff training sessions –Computer fairs –Product demonstrations –Guest speakers Brochures and Flyers A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 5

6. Purpose: communicate from support group to end users Popular in large companies where support staff does not regularly contact other workers Formats: –Printed –Distributed electronically Newsletters A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 6

7. Purpose: summarize and promote recall of material covered in training session –Common example: printouts of PowerPoint slides Usually short and address a single topic May be distributed online Handouts and Training Aids A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 7

8. Purpose: supplement vendor documentation and trade books with information specific to organization or computer facility Structure: Tutorial format: guides user step-by-step through hardware or software features Reference format: all material on each topic is covered in a single location Combination format: tutorial plus reference User Guides, Handbooks, and Manuals A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 8

9. Purpose: Provide convenient access to information Replace or supplement printed materials Features: –Information presented must be succinct –Use of hypertext links and index searches provide powerful tools to locate information quickly –Increasing in popularity and convenience Tip: Not all users are comfortable using online materials Online Help Systems A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 9

10. Purpose: formal and informal online communications: –With external clients and vendors –With internal end users and work colleagues Caveats: –Messages project an image of the organization and support specialist –Use good technical writing skills Tip: Growth in use of these communications emphasizes the need for excellent writing skills by user support specialists E-mail and Chat Messages A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 10

11. Purpose: provide access to support materials on the Web –Need to be organized and written so users locate information quickly and easily –Must be short but contain hypertext links to additional information Image of organization is at stake in Web documents Ongoing challenge: keep Web-based support information current and accurate Web Pages A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 11

12. Purpose: organizational correspondence accounts for a significant portion of computer use –Proposals –Letters –Memos –Needs assessment reports –Performance appraisals –Other correspondence Ability to prepare basic business correspondence is an important user support skill Proposals, Letters, and Memos A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 12

13. Purpose: procedure steps and checklists 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 9) Procedural and Operational Documentation A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 13

14. Purpose: help end users or support agents 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 A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 14

15. Differences in: –Writing style –Type of information communicated –Organization of document –Goals How Technical Writing Differs from Other Writing A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 15

16. Economical writing style Begins with most important information first Communicates information vital to reader’s productivity Uses style and format that helps reader understand a sequence of events Is concise, but not cryptic Contains pointers and cross-references Focuses on information, not entertainment Technical Writing Characteristics A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 16

17. Strategies –Use short, simple, declarative sentences, phrases, and lists –List a sequence of steps in the order performed –Include pointer, a reference to location where reader can find more information on a topic –Use format elements to help reader understand: Organization of information Transitions between topics –Avoid: Run-on sentences Humor Calling attention to writer’s personality or style Technical Writing Characteristics (continued) A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 17

18. 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 system How Technical Documents Are Organized A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 18

19. Common Organization for Technical Documents Introduction –Purpose of document –Intended audience –Why read document Body –Specific task steps –Common problems users encounter Summary –Pointers to additional information A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 19

20. Who is target audience? What does audience already know? What does audience need to know? What should audience be able to do when finished reading document? How will document be transmitted to audience? Document Planning A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 20

21. Help the Reader Target reading level at 8 th or 9 th grade –Most word processors include a readability index Tell reader who intended audience is –Organize material so experienced readers skip basic materials State document’s purpose in first sentences Tell readers what tasks they can perform after completing the document Tailor document to the media –Printed : generally longer; help readers with topic transitions –Online : generally shorter; help readers with pointers to additional information A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 21

22. 1. Generate idea or feature list 2. Organize list into a logical sequence (outline) 3. Expand outline into a first draft 4. Edit draft for clarity 5. Arrange for outside review 6. Revise draft into final form 7. Proofread final document Steps in the Technical Writing Process A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 22

23. Step 1: Generate Idea List Brainstorm : technique to generate a list of potential topics During brainstorming, exclude nothing Don’t worry about whether a topic is: –Major or minor –Useful or not –High or low priority A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 23

24. Arrange topics into logical sequence –Identify major and minor topics Cut and paste to try different sequence of ideas –Use word processor’s outline feature as tool Final organization should answer question: In what order does a reader need to know this information? Step 2: Organize Idea List into Outline A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 24

25. Strategies –Paragraphs have topic sentences –Transitions between paragraphs and sections –Define terms –Format features Style elements Format consistency Lists and tables Step 3: Expand Outline into First Draft A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 25

26. Style elements help reveal document structure –Chapter or modular organization –Fonts –Capitalization –Centering –Indentation –Underlines –Bullets and numbered lists Format consistency helps ensure consistent use of style elements –Use style sheets and templates in word processor Lists and tables help reader locate information quickly –Use instead of long narrative passages Step 3: Expand Outline into First Draft (continued) A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 26

27. Pass 1: Eliminate extra words Pass 2: Perform format consistency check –Consistent use of fonts for headings, subheadings, indentation, centering, boldface, italics, and underlining –Tip: Format feature overuse detracts from document Pass 3: Perform technical accuracy check –Test procedural or technical steps –Eliminate errors in instructions –Check URLs to modify dead links Step 4: Edit Draft A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 27

28. Purpose Identify and clarify 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 Step 5: Get Outside Review A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 28

29. Incorporate revisions into document Tip: When an edit pass results in marginal improvements, consider it done Step 6: Revise Draft A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 29

30. Final pass through document prior to publication Look for: Inconsistent capitalization and punctuation Inconsistent font use Extra spaces between words and sentences Incorrect page breaks Step 7: Proofread Final Draft A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 30

31. Analogy: describes how unfamiliar concept is similar to familiar concept Repetition 1. Introduce 2. Explain 3. Summarize Consistent word use –Use consistent word to refer to each concept Avoid varying: 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 events clearly occurred in the past Technical Writing Strategies A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 31

32. Sample Page from a Style Sheet A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 32

33. Technical Writing Strategies (continued) A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 33 Parallel structure: similar items are treated consistently throughout a list or document

34. Clutter Inappropriate typefaces Gender references Unclear referents Passive voice Nominalization Wordiness Jargon Undefined acronyms Dangling phrases Common Technical Writing Problems A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 34

35. Use graphics: –To illustrate or highlight point –Not for decoration Use formatting: –To help locate information or understand topic –Use sparingly and consistently Include considerable white space Use at least 10 point body text –Larger for slide shows, brochures, flyers Left-align most body text –Centered and block-justified text are harder to read Justified text is aligned at both the right and left margins like this Clutter A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 35

36. Serif typeface: includes fine lines (serifs) that project from the top and bottom of characters –Frequently used for body text Sans serif typeface: does not have serifs –Often used for titles and headings Specialty typeface: type style intended for special use to draw attention to text –Save for informal use Invitations, brochures, flyers Inappropriate Typefaces A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 36

37. Example Typefaces Which is most readable? This is an example of a 28 point serif typeface called Goudy Old Style. This is an example of a 23 point sans serif typeface called Arial. This is an example of a 32 point script typeface called Brush Script. A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 37

38. 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 A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 38

39. Referent: concrete word or concept that is designated (referred to) by another word The referent of words such as it, them, this, 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 A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 39

40. Active voice: sentence in which the subject performs the action indicated by the verb –Example: The project team filed its final report. –Use active voice to make text livelier and more interesting Passive voice: sentence in which the subject receives the action indicate by the verb –Example: The final report was filed. –Avoid passive voice Passive Voice A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 40

41. Nominalization: use of –tion, -ing, - ment 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 A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 41

42. 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 or utilization document instead of documentation added instead of additional Can you think of other examples? Wordiness A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 42

43. Jargon : words 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 Tip: If you use jargon terms, define them first Jargon A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 43

44. Acronym: word formed from the initial letters of words in a phrase –Example: RAM is an acronym for random access memory At first use of acronym: –Spell out the words –Then include the acronym in parentheses –Example: digital video disc (DVD) Tip: Include acronyms in a glossary Tip: Don’t create unnecessary new acronyms –Example: Technical Writers Against Unnecessary Acronym Use (TWAUAU) Undefined Acronyms A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 44

45. Dangling modifier: word or phrase at beginning or end of sentence that adds little meaning –Example: The installer will verify that the user’s PC is operational, of course. Eliminate the word (or phrase) or include it elsewhere in the sentence Dangling Modifier A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 45

46. Outline tool Spell checker Custom dictionary Thesaurus Grammar checker Readability index Desktop publishing features Collegiate dictionary Technical Writing Tools A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 46

47. Content Organization Format Mechanics Document Evaluation Criteria (Overview) A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 47

48. Is information relevant? Is information timely and accurate? Is coverage of topic complete? Content A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 48

49. Is information easy to locate? Are transitions between topics identifiable? Can user get in and out quickly with the right answer? Organization A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 49

50. Does layout help guide the reader? Is format consistent? Format A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 50

51. Are words spelled correctly? Is it grammatical? Is writing style effective? Mechanics A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 51

52. User support staff write a variety of types of documents to communicate with end users, coworkers, vendors, and managers Goal of technical documents: effectively and efficiently communicate information needed by the reader Technical writing: –Defines characteristics of target audience and tasks the writer wants readers to be able to do –Uses short words and sentences and an organization that helps locate information Chapter Summary A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 52

53. Chapter Summary (continued) The technical writing process includes these steps: 1. Generate idea or feature list 2. Organize list into a logical sequence (outline) 3. Expand outline into a first draft 4. Edit draft for clarity 5. Arrange for outside review 6. Revise draft into final form 7. Proofread final document Layout of document and formatting helps readers know what is important and identify transitions between topics Technical writers use analogies, repetition, consistent work use, and parallel structure A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 53

54. Chapter Summary (continued) Successful writers avoid clutter, hard-to-read typefaces, gender references, passive voice, unclear referents, wordiness, jargon, acronyms, and dangling modifiers Software tools that aid writers include an outline tool, spell checker, thesaurus, and grammar checker Four criteria to evaluate technical documents –Content –Organization –Format –Mechanics A Guide to Computer User Support for Help Desk & Support Specialists, Fourth Edition 54