[Discuss] Have you done a technical book review?

[Daniel Barrett]

On November 19, 2013, Greg Rundlett (freephile) wrote:
>I'm interested to know firsthand how other authors and contributors worked
>through the publication process.

I've written a bunch of O'Reilly books and have done a bunch of tech
reviews. If a paragraph is badly written, by all means suggest a
rewrite, but if the whole book is badly written, you are definitely
not obligated to fix it. It's perfectly OK (in the worst case) even to
send the whole manuscript back with, "This writing isn't ready for
prime time, and here are 10 examples why."  Your time is too valuable
to be wasted by bad writers.

The most value that tech reviewers can provide comes from:

- Expert knowledge: pointing out something that the author has overlooked,
has gotten technically wrong, or hasn't realized is controversial.

- Clarity: the author tried to explain something, but the intended
audience won't understand it. Suggest improvements.

- Typos in code or program output.

- Technical errors or ambiguity in illustrations.

Tech reviewers generally don't need to worry about:

- Typos in English, which get fixed in copyediting.

- Typsetting issues like wrong margins, bad hyphenation across lines, etc.,
which get fixed in copyediting.

Hope this helps.

--
Dan Barrett
dbarrett at blazemonger.com