Monday, 4 April 2005
Dear Tech Reviewer
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:
Update I keep thinking of more. (Also be sure to read the comments.)
- 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.
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 ...
- 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..."?