Peer Review Editing Checklist for Writers

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.

 

A Collaborative Writing Model for the Social Web

 

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?