mike's web log

 

Blog Search


(Supports AND)

 

Google Ads

 

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

 

Quote

Without variables, programs would not be very interesting.

Kenny Kerr



 

Navigation






<April 2014>
SMTWTFS
303112345
6789101112
13141516171819
20212223242526
27282930123
45678910


 

25 Most-Visited Entries

 

Categories

  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
 

Blogs I Read

 

Contact

Email me
 

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 4/3/2014

Totals
Posts - 2298
Comments - 2480
Hits - 1,620,133

Averages
Entries/day - 0.58
Comments/entry - 1.08
Hits/day - 410

Update every 30 minutes. Last: 1:35 PM Pacific

 
   |  Dear Tech Reviewer

posted at 12:29 PM | | [2] |

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 ...

[categories] ,