Category Archives: Writing and Editing

Nine Ways to Engage Customers in Technical Documentation

Posted on by
2

Persuasion involves making compelling appeals to both our emotions and logic. Most people don’t consider technical writers natural persuaders, but the discipline of technical communication actually falls under the umbrella of Rhetoric, in most college programs for technical communication.

With its factual subject matter and informative style, technical communication appeals mostly to our logical sides. What many are surprised to learn is there have always been subtle ways that technical writers also appeal to our emotions.

Examples of emotional persuasion at work in technical documentation include the way technical writers directly address customers as “you,” the parallel writing structures, and the sense of trust technical documentation instills, through the credible presentation of detailed information.

Here are some traditional ways technical writers motivate customers to stay engaged with the text, complete steps, and refer back to the instructions, the next time they’re stuck.

1. Credibility

The accuracy and completeness of technical content—whether print or online– is the most important factor in convincing customers to follow the instructions or  refer to the instructions again. It doesn’t matter how pleasing content is presented or how well-written it is. If the steps are inaccurate or incomplete, your content—and product—loses credibility.

2. Visual Design Cues

Headings, subheadings, and bulleted lists help customers more easily scan the text. These navigational cues also create a mental hierarchy—in classic rhetoric what’s known as a schema— that structures the way readers think about our products. This technique is especially useful when explaining or understanding how products work, or grouping similar concepts, including tasks and roles. Templates and checklists reinforce these schemas–what in instructional design are known as learning scaffolds.

3. Entry Points

Convincing customers that they’ll find the information they’re seeking is one of the most important challenges technical writers face. Navigational aids—such as traditional TOCs, headings, online breadcrumb trails, print cross-references, online links, indexes, and other metadata—all reassure readers that the information they’re looking for is present and findable—and that the content is worth referring to, in the first place.

4. Concise Writing

In an increasingly visual, online world, concise writing–the hallmark of a task-based writing approach—is more important than ever to keeping distracted readers’ attention and encouraging customers to complete required actions.

5. Active Voice

Addressing the audience directly as “you” (with active verbs), not only ensures more concise writing, it also sets up a conversational and lively tone.

6. Parallelism

In Effective Rhetoric, Effective Writing: Parallelism in Technical Communication, Helen Fawcett shows how the repetition of parallel structures—as applies to headings, transitional elements, steps, and sentence parts—helps effectively group and present similar information, as well as create a sense of rhythm.

7. Visuals

Technical writers use tables, charts, graphs, and illustrations to present or reinforce information. Visual techniques apply even more so, for today’s social-media savvy customers, who prefer to process pictures, sounds, and video rather than text.

8. Consistent, Plain Language

Using the most concise terms consistently across all your media ensures that customers understand the underlying concepts and apply them, appropriately. Introducing different terms for the same concepts only frustrates readers and complicates translation for global audiences.

9. Professional Editing and Layout

In a “good enough,” real-time publishing world, the bar for professional-level documentation is lower than it used to be. It’s still worth remembering that writing, typographical, or other formatting issues can detract from our customers’ overall impression of a document’s usefulness, as well as its actual usability. Both factors affect how much customers want to use your documents.

Your Tips or Comments

How do you motivate customers to engage with the product documentation? Are digital media, audience-generated content, and personalization replacing, changing, or reinforcing the traditional ways we encourage customers to refer to and engage with our content?

As marketers incorporate a more informative, logical style of writing into their
content, how relevant will technical writers remain, if we don’t incorporate
more emotional appeals, directly into the user assistance? Wouldn’t this style
of writing be more natural to our customers?

Is there any way to reconcile a more affective approach to technical documentation, with content re-use and globalization requirements? or must by definition, these approaches remain incompatible?

About This Blog: Copyright Information

Contacting the Author: Content for a Convergent World – Peg Mulligan’s Blog

Peer Review Editing Checklist for Writers

Posted on by
7

Complete all sections of this editing checklist during the document’s peer review. (Someone other than the writer should complete the checklist.) Plan on spending at least one full day on the peer review, perhaps longer, depending on the size of the document.

The peer review editing checklist involves completing a copy edit, completing a content edit, and then meeting with the writer to discuss your suggestions.

If you can think of any additional editing or proofreading suggestions, please feel free to add your tips in the comments. Thanks in advance for your help.

Copy Edit

Check the following items during the copy edit:

1. Scan every line for errors (for example, extra or missing spaces, duplicate lines, words that run together).

2. Ensure the text always follows a heading. Headings should not follow headings, without text separating them.

3. Ensure headings appear in the correct order. A heading 3 should follow a heading 2. A heading 4 should not follow a heading 2; it should follow a heading 3.

4. Ensure that capitalization in headings adheres to the style guidelines defined in The Chicago Manual of Style, Microsoft® Manual of Style for Technical Publications (if applicable), or your own organization’s style guide. (Capitalize the first, last, and important words. Don’t capitalize a, the, and for.)

5. Read through for missing words, incomplete sentences, and grammatical errors.

6. Scan for widows or orphans in text, headings, lines, or list items.

7. Ensure the style of the document follows the conventions defined in The Chicago Manual of Style, Microsoft® Manual of Style for Technical Publications (if applicable), or your own organization’s style guide.

8. Check cross references to ensure they point to the correct page.

9. Verify that acronyms are first spelled out. After defining the acronym, you can use the acronym without the word.

10. Ensure that all product names are formatted correctly, especially in the table of contents and the index.

11. Ensure that digits are used for numbers 10 and above, and that numbers nine and below are spelled out.

12. Check for correct and consistent capitalization.

13. Verify that acronyms are spelled out and that the acronym is enclosed in parentheses.

14. Check that in subsequent occurrences of an acronym the words are not spelled out.

15. Verify that all lists contain more than one item.

16. Ensure lists have consistent capitalization and punctuation.

17. If a list item is a complete sentence, the item should start with a capital letter and end with a period.

18. If each list item is NOT a complete sentence, each item should start with a lowercase letter and not end with a period.

19. When the text that introduces a list is an incomplete sentence that is completed by each list item, use a colon (:) at the end of the introductory text. Do not capitalize the first letter of any list item and do not put a period or comma at the end of any list item.

20. Check that figure numbers are consecutive.

21. Check that the figure title reflects the actual figure.

22. Check figures for alignment of text columns.

23. Check each reference to a figure to ensure it points to the correct page.

24. Check that the figure number in the text matches the figure number in the caption.

25. Check that the font in the figures is correct and consistent.

26. Check the index. Ensure that all product references are formatted correctly. Ensure the index follows the conventions discussed in The Chicago Manual of Style, Microsoft® Manual of Style for Technical Publications, if applicable, or your own organization’s style guide.

Content Edit

Check the following items during the content edit:

1. Ensure it is clear who the intended audience is and that the document speaks to the intended audience

2. Look at text that is primarily explanation or description and be sure it is thorough and effective.

3. Check the totals in figures to be sure they are correct. Do the math.

4. Check that the items from a figure when described in the text reflect what’s on the figure.

5. Verify that the preface section “How This Manual is Organized” actually reflects the organization of the document.

6. Read the document for clarity. Ensure it makes sense. Circle any areas that you do not understand, are contradictory, or appear to be highly ambiguous.

7. Note any areas that appear to have missing information. Check for missing sections that would make the document more usable.

8. Make sure the steps in a process relate to the overall process.

9. Ensure items in a numbered list are task-oriented and can be followed.

10. Make sure that the figures or examples relate to the discussion.

Meeting with the Writer

When meeting with the writer, keep these tips in mind:

1. Arrange to meet with the writer to review and discuss your edits.

2. Document any unresolved issues.

3. Notify the group by email that you have completed the review.

 

“Never Call a Stomach a Tummy without Good Reason” ~ Takeaways from Strunk and White (2009 Edition)

Posted on by
Reply

In my last post, I waxed a bit nostalgic about William Strunk and E.B. White’s Elements of Style turning 50 this month. I also summarized my favorite tips from this classic writing guide, including using active voice, omitting needless words, using specific, concrete language, and above all else, striving for clarity.

Before concluding, I highlighted the advice that it’s best not to break rules of grammar, without first understanding the rules. And I provided White’s eloquent description of style as “what you are, rather than what you know” (p. 84).

In the following lists, I provide takeaways (again, just some of my favorites) from each section of Strunk and White. You can’t go wrong, applying these rules to your next document or blog post. I plan on using this list as my own personal style sheet, when I want to review a rule. I hope these tips help you as well.

Elementary Rules of Usage

The following list provides rules of usage for punctuation and grammar:

  • “A common error is to write it’s for its, or vice versa. The first is a contraction, meaning it is. The second is a possessive” (p. 1).
  • “In a series of three or more terms with a single conjunction, use a comma after each term except the last…This comma is often referred to as the serial comma” (p. 2).
    [Peg’s Note: Writers and editors often disagree on the use of the serial comma. Technical writers most often use the serial comma, as it can sometimes resolve ambiguity.]
  • “Place a comma before a conjunction introducing an independent clause” (p. 5).
  • “Use a colon after an independent clause to introduce a list of particulars, an appositive, an amplification, or an illustrative quotation. A colon tells the reader that what follows is closely related to the preceding clause…It usually follows an independent clause and should not separate a verb from its complement or a preposition from its object” (p. 7).
    [Peg’s Note: Please never, never use a colon after a verb, preceding a bulleted list. It gives me the willies.]

Elementary Principles of Composition

The following list provides principles of writing:

  • “Choose a suitable design and hold to it. A basic structural design underlies every kind of writing” (p.15).
  • “Use the active voice.  Many a tame sentence of description or exposition can be made lively and emphatic by substituting a transitive in the active voice for some such perfunctory expression as there is or could be heard” (p. 15.)
  • “Use definite, specific, concrete language” (p. 21).
  • “Omit needless words” (p. 23).
  • “Avoid a succession of loose sentences (p. 25). This rule refers especially to loose sentences of a particular type: those consisting of two clauses, the second introduced by a conjunction or relative” (p. 25).
  • “Express coordinate ideas in similar form…following the principle of parallel construction” (p. 26). [Parallel construction is especially important in bulleted lists.]

A Few Matters of Form

The following list provides tips on matters of form:

  • “Exclamations. Do not attempt to emphasize simple statements by using a mark of exclamation” (p. 34).
  • “Hyphen. When two or more words are combined to form a compound adjective, a hyphen is usually required. Do not use a hyphen between words that can better be written as one word (p. 34). The steady evolution of the language seems to favor union: two words eventually become one, usually after a period of hyphenation (p. 35). [When in doubt, consult a dictionary.]
  • “Quotations. Typographical usage dictates that the comma be inside the marks, though logically it often seems not to belong there” (p. 36).
  • “Syllabication. When a word must be divided at the end of the line, consult a dictionary to learn the syllables between which divisions should be made” (p. 38).

Words and Expressions Commonly Misused

The following list provides tips on how to avoid commonly misused words and expressions:

  • “And/or. A device, or shortcut, that damages a sentence and often leads to confusion or ambiguity”
    (p. 40).
  • “Can. Means “am (is, are) able.” Not to be used as a substitute for may” (p. 42).
    [In technical documents, “can” is almost always used.]
  • “Data. Like strata, phenomena, and media, data is a plural and is best used with a plural verb. The word, however, is slowly gaining acceptance as singular” (p. 44).
  • “Etc. In formal writing, etc. is a misfit. An item important enough to call for etc. is probably important enough to be named” (p. 45).
  • “-ize. Do not coin verbs by adding this tempting suffix. Why say utilize when there is the simple, unpretentious use? (p. 50).
  • “Secondly, thirdly, etc. Unless you are prepared to begin with firstly and defend it (which will be difficult), do not prettify numbers with –ly. Modern usage prefers second, third, and so on” (p. 57).
  • “Avoid splitting infinitives unless you want to place unusual stress on the adverb.  Listen to your ear to decide whether to split” (p. 58). “The split infinitive is another trick of rhetoric in which the ear must be quicker than the handbook. Some infinitives seem to improve on being split” (p. 78).

An Approach to Style

In Chapter 5, which White authored entirely, he offers the following reminders for improving  writing style:

  • “Place yourself in the background” (p. 70).
  • “Do not overstate” (p. 73).
  • “Do not explain too much. It is seldom advisable to tell all (p. 75).
  • “Avoid fancy words. Do not be tempted by a twenty-dollar word when there is a ten-center handy, ready, and able” (p. 76).
  • “Years ago, students were warned not to end a sentence with a preposition;  time, of course, has softened that rigid decree. Not only is the preposition acceptable at the end, sometimes it is more effective in that spot than anywhere else” (p. 78).
  • “Be clear” (p. 79).
  • “Do not use initials for the names of organizations or movements unless you are certain the initials will be readily understood. Write things out… A good rule is to start your article by writing out names in full, and then, later, when your readers have got their bearings, to shorten them” (p. 81).
  • As for the advice, “Never call a stomach a tummy without good reason” (p. 77), White reminds us to avoid “the elaborate, the pretentious, the coy, and the cute” (p. 76).

    Peg’s Note:     I think advisors as helpful as Strunk and White would permit us to still ask how our kids’ tummies are doing, after stomach aches. They would probably encourage us, however, to consider being cute in this way, as only the exception to the rule.

A Collaborative Writing Model for the Social Web

Posted on by
1
 

In my last post How to Deploy Social Media ~ a Call to Arms, I promised to explore the activities and social media tools that as a technical communicator, I can use at each stage of the product development life cycle to collaborate with members of my user community, as we develop audience-centered content for the social web.

The stages that I am using as a writing framework are “awareness, attention, engagement, execution, and extension” (as described in Chris Brogan’s post: Pirate Moves-From Awareness to Extended Action.)  I am also using as a model the five stages that apply to almost all software usage:  unaware, interested, first-time use, regular use, and passionate use”(see Joshua Porter’s Designing for the Social Web: The Usage Lifecycle).

Both Brogan’s “continuum” of relationship-building stages” and Porter’s “Usage Life-Cycle” mirror the five traditional stages of the writing process: prewriting, drafting, revising, editing, and submitting. In the sections that follow, I interweave these related processes, providing specific examples of how I would use social media tools for collaboration, at each stage of the life-cycle. I also incorporate examples of how Charlene Li and Josh Bernoff used social media tools in their collaborative writing process, drafting the BusinessWeek Bestseller, Groundswell.

Awareness

According to Brogan, “If you’re selling the coolest software [or Peg’s note: software documentation] in the world, but no one knows that, how are you going to sell it? [or Peg’s note: get someone to follow your instructions?] What comes first is awareness.”  For Porter, this is the Unaware stage in the usage life-cycle: “This isn’t so much a stage as it is a starting point.”

Here are some ways technical communicators can use social media tools to increase awareness of their documentation initiatives and to encourage collaboration with their primary and secondary audiences:

  • In addition to traditional Release Notes (the documentation users are most likely to refer to), use podcast or video to highlight information about new features, guidelines for use, inter-operability issues, operational notes and restrictions, and software problem reports.
  • Use podcast or video to supplement the How-To Use this Doc Set (a guide that often accompanies lengthier doc sets).
  • Use a blog or forum to make users aware of legacy docs and to solicit feedback for improvements, recommendations on how to organize the doc set, and input on the preferred medium for delivering online help.
  • Use a combination of social media tools (including the blog, wiki, forum, mini social network, and twitter) to complete an audience analysis & gain more detailed understanding of primary and secondary audiences, as well as the purpose of all content deliverables.
  •  Distribute a documentation plan, via a wiki, so community members can anticipate exactly what deliverables you plan on providing content for and can provide input on what types of content they would most prefer.
  • Welcome community members and ask for their help collaborating on content, by revising content via the wiki, adding new content, and helping to edit content.
  • Use Twitter to announce when you’ve posted any new content, podcasts, or video to your blog, forum, doc wiki, or company website.

Attention

Brogan describes the Attention stage as “a bit more than awareness. It means that people are giving you a little bit more of their time. They expect something back for this, be that entertainment, or a perception of value, or a sense of participation.” Porter describes this usage stage as ‘Interested: These people are interested in your product, but are not yet users. They have lots of questions about how it works and what value it provides.”

Here are some ways technical communicators can use social media tool to increase attention and participation from their content collaborators:

  • Post early outlines of the content and solicit feedback on the doc blog, wiki, and user forum.
  • Include “talk pages” parallel to each wiki page, where contributors discuss (and sometimes fight over) what ought to be included (Groundswell, p. 25).
  • Ask users for real-world examples or scenarios that they want the doc to help them solve.
  • Share any bookmarks, related to background research on the technology or product you are documenting, through social bookmarking sites. Authors Charlene Li and Josh Bernoff, of Groundswell, used social bookmarking in this manner to share links about their research and book on Del.icio.us. [del.icio.us/the groundswell].
  • Ask your community members (reviewers and co-authors in the next two stages) to share their technology and product-related bookmarks, allowing them to become collaborators with the technical communicator, not just in the writing, but also in the research stage, of the writing process.

Engagement

Engagement, to Brogan, is ‘the sustained interaction between you (or your product or brand or service) and your buyer [again for the technical communicator, the doc user]. Use tools to maintain two-way interactions. Look for ways to engage in a participatory way.’ For Porter, ‘First-Time Use’ involves “people using your software for the first time, a crucial moment in their progression.”

Here are some ways technical communicators can “capture, maintain, and manage collective knowledge” (Technical Communication in a Social Media World) and use social media tools to further engage their content collaborators:

  • Post complete drafts to the wiki and solicit comments.
  • Use discussion boards, based on primary & secondary audiences, as a way to discuss topic threads in greater detail. For example:  Intuit’s quickbookgroup.com forum for small business owners, using its QuickBooks product (Groundswell, p. 26).
    As Li and Bernoff suggest, provide users a place to provide tips, similar to www.ebaywiki.com. (Groundswell, p. 26).
    Collaborate with users to develop a glossary, for example: glossary.reuters.com (Groundswell, p. 26).

Execution

In the Execution stage, Brogan states “we’re talking about the actual event, or the purchase, or the delivery of information.” Porter describes this stage as “Regular Use”: “These people are those who use your software regularly and perhaps pay for the privilege.”

Here are some ways that technical communicators can use social media tools to execute their content delivery:

  • Incorporate all review comments from the community and post a completed draft to the doc wiki.
  • Transition into a more moderator-like role, facilitating as community members rewrite the content and directing members to appropriate content.
  • Organize content on the social web through tagging, enabling others to more easily locate the documentation. For example, when creating Groundswell, Li & Bernoff organized the web using delicious “to create a set of tags for each chapter, neatly organizing Web sites and articles we’d found.” [del.icio.us/the groundswell].
  • Use RSS and widgets to inform your community members of significant updates to the audience-centered content. According to Li and Bernoff, RSS and widgets “give people the ability to consume and process more social content” (Groundswell ,p. 32).

Extension

Chris Brogan describes Extension as “a way of moving from what happened to what happens next” and “the feeling that your buyer was part of something.” Porter calls this stage Passionate Use:  “These people are the ultimate goal: passionate users who spread their passion and build a community around your software.”

Here are some ways that technical communicators can use social media tools to extend their community-building efforts and to make an impact, not just on the next iteration of the content, but on improving the product:

  • Continue to revise and fine-tune the content, acting in a more editorial role.
  • Continue to use the blog, user forums, and doc wiki, as a place to receive documentation feed-back.
  • Actively solicit customer feedback through surveys and follow-up calls.
  • Complete usability tests of the doc with members of the community, showing the live testing process through podcasts, to heighten a sense of participation and investment in the product.
  • Report back to Product Management what documentation topics are most active on the social web and consider those as likely places to review, improve, or add-on to the product’s functionality.

Summary

In summary, the life-cycle approach for designing audience-centered content for the social web could work this way for technical communicators (or any collaborative writer):

  • During the Attention and Interest stages, convince community members to locate, follow, and contribute to the user instructions.
  • During the Engagement stage,”capture, maintain, and manage collective knowledge,”  enabling the community to rewrite the content later (see Technical Communication in a Social Media World).
  • During the Extension stage, reinforce passionate usage of both the content and more importantly, the product.
  • Though I propose these examples from the perspective of a technical communicator, the same life-cycle approach applies to most other software development disciplines and is the best framework for deploying social media in the large enterprise.

What are your thoughts on the collaborative activities that I propose for technical communicators, at each stage of the usage life-cycle? If you represent a different discipline, what social media tools would you use at each stage, as relates to your different goals? Would this collaborative writing approach still apply in agile development settings, where both the product and documentation are delivered by module, in short, iterative cycles?