David Barnes @ Packt

Whether you're writing for O'Reilly, Packt, some other publisher, or for the web -- the Missing Manual author guidelines (PDF, 17 easy-to-read pages) are packed with great advice. Check them out.

On writing style:

•  Set software actions in the present tense. We want Missing Manuals to read as
if  you’re  standing  over  the  reader’s  shoulder,  guiding  her  through  a  series  of
steps.  Software  actions  thus  happen  as  you  go.  So  instead  of  “The  icon  will
blink,” try “The icon blinks.” Save future tense for things that will happen later.
•  Write  as  precisely  as  possible. Avoid  sentences  that  start  “There  are”  as  in,
“There  are  four  separate  areas  that  make  up….”  Instead,  try  something  like
“Four separate areas make up a Keynote screen.” Or “Keynote has four separate
areas that make up its screen.” You get the idea.
•  Show  clear  cause and  effect. When you want  to  explain  how  a program will
respond to an action on the reader’s part, avoid: “Click OK and Word reformats
the document.”  Instead go  for:  “If you  click  the OK,  then Word  reformats  the
document.”  Or  “When  you  click  OK, Word  reformats  the  document.”  Also,
when you have  a  list of  actions within  a  sentence, use  “and  then”  to  introduce
your  final  step.  If  you  have  just  “and,”  readers  might  wonder  whether  they
should be performing  two  actions  simultaneously. But  if you have  just  “then,”
you’ve  committed  a  grammo  because  series  of  actions  needs  a  conjunction  to
link the last one to the rest of the sentence, and “then” is not a conjunction.
•  Show  readers  the  right  order  of  events.  When  explaining  how  to  do
something,  tell  readers  where  they  should  be  before  telling  them  what  they
should do. For example: "In the Open dialog box, select the file...." (Not, "Select
the file in the Open dialog box.") 

And a favorite peeve of mine (and every tech book editor, perhaps)...

So, Missing Manual Rule Number One: Your  job  is  to  act  as  the  reader’s guide as you
take her  through  a  tour of how  the  software works.  In other words, keep  the  following
point in mind with every feature you describe:

What’s it for?
Nothing makes  a  reader want  to hurl  a book  across  the  room more  than  a passage  like
this:  “In  the  Implement  Freen  Modules  dialog  box,  you  have  options  that  let  you
implement Freen modules in various ways.”

With each  feature, you should never  just say how  it works. You should always, always,
always help  readers understand why  they would want  to use  a  feature. A  sentence  like
“Open the Preferences window if you want to adjust your system preferences” is not only
dull, it also fails to advise the reader that, for example, he can make his monitor easier to
read by changing its preferences. Here are some examples of how to integrate this advice
smoothly into your sentences:
•  “You’d find this useful in case of, for example, a power outage.”  
•  “There’s pretty much only one instance when you’d want this option turned off,
and that’s when…”  
•  “Although few people will use this setting, it’s designed to...”  
•  “Many PC fans don’t realize quite how powerful this checkbox can be.”  
•  “Microsoft’s  engineers  may  have  been  overly  optimistic  in  assessing  the
importance of this feature.”
Here’s  where  you  can  really make  a  difference,  setting  yourself  apart  from  the  robot
authors  who  just  catalog  features.  Readers  love  these  assessments.  Don’t  just  tell  the
readers; advise them.

O'Reilly Missing Manuals are some of the best selling tech books out there. Of O'Reilly's Top 25 sellers last week, 14 were Missing Manuals -- that's close to two thirds. Anybody who wants to write books that people want to buy should check them out.

There's nothing secret or unique about the Missing Manuals formula. Most of the advice in the document is best practice for accessible, interesting technical writing. What O'Reilly and Pogue Press has achieved is to reliably deliver books that meet these guidelines -- and that's the real challenge for publishers, editors, and authors.