Posted on by Yoel Strimling

This Worked for Me: How Do You Want That Edited?

By Yoel Strimling

While technical editors might be great, most of us aren’t miracle workers. We have deadlines, resource issues, multiple tasks, and so on. While we want the documents we send to our readers to be as good as they can be, we realize that we can’t do everything, and that some sort of compromise needs to be made. The “golden triangle” of Good/Cheap/Fast calls on us to pick only two.

So what do we do? We have to let the document authors (be they technical communicators or engineers) know exactly what we can do and how long it will take us, and then help them plan accordingly. When everybody is “on the same page” and all expectations are clear, the editing process runs much smoother.


At the company I work for (CEVA), I’ve defined criteria and time frames for three different review levels, and I make sure that the document authors know exactly what they will get based on when they send it to me for review, In general, this works pretty well, although there are always last-minute emergencies:

Format Review

A format review is the minimum review that I do (this applies only to Word documents; for FrameMaker documents, this is irrelevant). It focuses only on the look and feel of the document, and uses the following criteria:

  • On the front cover page, the branding is up to date.
  • In the headers, the following are correct:
    • The book title
    • The version number and date (in architecture documents)
  • In the footers, the copyright year(s) is correct.
  • The following front matter sections are correct:
    • In the Documentation Control section:
      • The history and approval tables have up-to-date version numbers and are complete.
      • All text that is supposed to be hidden (author and approval table) is hidden.
    • In the Disclaimer section, the product list is up to date.
    • In the Support section, the email addresses are correct.
    • In the Sales/Support Centers section, the contact table is up to date.
  • There are no figure/table/example captions in the Table of Contents (or any other text that does not belong).
  • There are no manual page breaks.
  • The document’s pagination is correct, as follows:
    • Chapters start in a new section.
    • There are no blank numbered sections.
    • Tables are formatted correctly (for example, there are no broken rows).
    • There are no orphaned bullets, captions, figures, or tables.
    • There are no broken paragraphs (that is, paragraphs that are split over two pages).
    • There are no extra paragraph marks.
    • The text is spaced properly on the page.
  • There are no broken cross-references.

The format review does not include putting the document into the company’s Word template.
The turnaround time for this type of review is (on average) one hour per 100 pages.

Basic Content Review

In a basic content review, I review the document for basic content issues (for example, correct word choice, spelling, and basic English grammar).

In addition to doing all of the format review criteria, this review looks for the following:

    • All instances of certain incorrect word choices, for example:
        • in order to > to
        • whenever > when
        • all the > all of the
    • All commonly confused words, for example:
        • affect/effect
        • than/then
        • once/after
        • since/because
        • may/can/might
    • All contractions (for example, can’t, won’t, isn’t)
    • All gender-specific language (for example, he, his, him)
    • All mistaken words (for example, bellow instead of below).
    • Basic punctuation issues (for example, double periods and missing commas)
    • All inappropriate uses of future tense
    • Incorrectly pluralized acronyms (‘s instead of s)
    • All instances of non-standard spellings, for example:
        • break point instead of breakpoint
        • KHz instead of kHz
        • off line instead of offline
    • Hard-to-understand or unnecessary words and phrases, for example:
        • Latinisms (i.e., e.g., etc.)
        • Shorthand acronyms (for example, HW instead of hardware, SW instead of software)
        • Wordy phrases (for example, in the event that instead of if, due to the fact that instead of because)
    • Incorrect capitalization in titles

    • Correct spelling and grammar of the document (via the Word spelling and grammar check)

The turnaround time for this type of review is (on average) half a day per 100 pages.

Extended Content Review

An extended content review is a detailed review of the entire document, in which I carefully read the document for clarity, accuracy, completeness, and relevance.

In addition to doing all of the format review and basic content review criteria, this review looks for the following:

    • The document is in the company’s Word or FrameMaker template.
    • The text is clear, complete, accurate, and relevant.
    • Repeated information (if required) is written consistently.
    • Sentences are coherent.
    • There is no contradictory information.
    • All bulleted lists are consistent in terms of writing style and punctuation.
    • Bullets or numbers are used correctly where needed (for example, in unordered or ordered lists, respectively).
    • Cross-references are formatted correctly.
    • Special text (for example, filenames or directories) are formatted correctly.
    • All figures and tables have captions.
    • Figures and tables are correctly referred to in the text.

    • All acronyms used in the document are present in the acronym table, and are coined correctly in the document.

If the document has procedures, the review also looks for the following:

    • All procedure prerequisites (if they exist) are written correctly and completely.
    • All procedure steps have clear and meaningful results.
    • All procedures have correct and clearly written purposes.
    • Every action needed in a procedure step is written clearly and completely.
    • No information or steps in a procedure are missing.
    • The WAR (Where > Action > Result) rule for actions is used correctly.

    • Titles/test descriptions/steps all match.

The turnaround time for this type of review is (on average) three days per 100 pages.

3 Replies to “This Worked for Me: How Do You Want That Edited?”

  3. This is really handy as I am looking at the next steps in my career and am applying for other jobs (hence the nom de plume — er, nom de type?).

    Thank you!

    Reply

Leave a Reply