About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

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

Always do right. This will gratify some people and astonish the rest.

— Mark Twain



Navigation





<March 2017>
SMTWTFS
2627281234
567891011
12131415161718
19202122232425
2627282930311
2345678

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  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 3/10/2017

Totals
Posts - 2420
Comments - 2551
Hits - 1,935,533

Averages
Entries/day - 0.48
Comments/entry - 1.05
Hits/day - 385

Updated every 30 minutes. Last: 2:11 AM Pacific


  12:29 PM

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]   ,

[2] |

 
http://www.mikepope.com/blog/DisplayBlog.aspx?permalink=1114&count=no
www.mikepope.com
crawl=CC-MAIN-2017-13
50543
application/http; msgtype=response
sha1:ZSP5DN2FO4SIZW6TUU5LGXVDLGGJPLDB
<urn:uuid:166bbb72-2477-43e0-9d51-dda1a4dfd309>
2017-03-29T09:17:44Z
96.31.33.35
sha1:GCE3HRCWPQMTOBZOWLKBC2LNYL6YRIRX
<urn:uuid:237f54fb-4426-4e6a-b70c-16ac6f9a4f75>
http://www.mikepope.com/blog/DisplayBlog.aspx?permalink=1114&count=no
response
<urn:uuid:3408402e-bbd2-4751-b8ca-465a6b906ce8>
robots: classic
hostname: ip-10-233-31-227.ec2.internal
software: Nutch 1.6 (CC)/CC WarcExport 1.0
isPartOf: CC-MAIN-2017-13
operator: CommonCrawl Admin
description: Wide crawl of the web for March 2017
publisher: CommonCrawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf