1. Original Entry + Comments2. Write a Comment3. Preview Comment

April 04, 2005  |  Dear Tech Reviewer  |  27000 hit(s)

Do you, as part of your job, review draft documentation for technical accuracy? IOW, are you a technical reviewer? If so, sit down, shut up, and listen to these helpful suggestions:
  • Answer the flippin' questions  Did a writer leave a question in the draft that says "Reviewers: is this right?" or "Reviewers: any other points I should make here?" You are that reviewer. Respond, already. The questions aren't there for decoration.

  • Don't ask us questions  Gee, how helpful is it for the writer if the reviewer, who is the technical expert, asks questions like "Is this correct?" or "Does it really work this way?" Your job is to answer questions, Mr. Curious.

  • Be assertive  Here's a little tip. If a writer sees a comment like "Consider adding information here about ...", and yon writer has a large stack of other documents to get through, how long do you think the writer will sit and "consider" your suggestion? If you guessed "zero time, because obviously the reviewer doesn't consider this essential," then you guessed right! If you don't insist, it ain't gonna happen.

  • Re-read your comments, for god's sake  A comment that is so poorly spelled or written that it can't be understood is just more wasted time for writer and reviewer, because guess what? The writer will darken your doorway at some point to get clarification. Writing an incomprehensible comment is basically saying "I wish to review this document twice."

  • Read ahead, or at least re-read  It's useless to get a comment like "We should talk ahout xxx" when xxx is in fact discussed two paragraphs later. Gee, thanks for paying such close attention to my topic ...

  • Don't argue with other reviewers  If you are adding comments to a document already reviewed by someone else, don't argue with the other reviewer in your comments. Go resolve your little familial disputes and get your story straight for the poor writer.

  • Honor the damn schedule  Getting tech review comments back after a document has been handed off for publishing isn't exactly helpful. Yeah, we know you're busy. So are we.
Update I keep thinking of more. (Also be sure to read the comments.)
  • You = technical, us = language  It's great that you are very concerned about how the documentation reads, but we actually have people who will fix the sentences and punctuation and spelling. Later, long after tech review. You're looking at drafts. We really want you to read for content, not to blue-pencil the doc with your ideas about recasting sentences. Here's your rule of thumb: make all the language edits you want, as long as you are editing terms and language for technical accuracy.

  • Think outside the dox  Way too many technical reviews involve a strategy that's something like "This sentence is not untrue. Ok, the next sentence is not untrue. The next one is also not untrue." Micro-reviews. The thing we writers often can use help with is what's missing? Put yourself in the reader's seat. If you were reading this stuff to actually learn about product features, what would you want to know? (But do not fall into the fallacy that you are our typical user. See Jeff Atwood's astute observation about the difference between you, the reviewer, and ordinary mortals.)

  • Make useful comments, for heaven's sake  What exactly are we supposed to make of comments like "I don't like this sentence" or "Mmmmmmm..."?
So that's this week's crop of suggestions. Stay tuned for another in our continuing series of telling people how to help us do our jobs ...

Tim Teebken   04 Apr 05 - 12:55 PM

If you raise something that you know is going to generate a significant issue in a comment (e.g., We're going to need a separate conceptual topic to address this), follow up with the writer in email or in person to make sure that they agree on the need for this additional task, and that the writer has the bandwidth to add the task to their schedule. Otherwise, there can be miscommunication on whether some comment in a document was something that definitely needed to happen, or was just a nice suggestion.

Doug Rothaus   04 Apr 05 - 1:01 PM

I would add a suggestion that, when something is incorrect, provide the correction. Too many times (once is too many) I have encountered a comment from a reviewer that says, "This is wrong.". My ego can take making a mistake. However, if you think about it, I'm the one who made the mistake. Hence, I don't know the correct answer. All it would take is a comment along the lines of, "This should say...".