Pre-Pub Reviewers

If I pointed you at this page, it’s because you have expressed curiosity about pre-publication review of a book I’m working on. Here I answer the usual questions about the process.

Note that this only applies for books that I’m actively seeking reviewers for. If I have not announced that I am looking for reviewers for Title X, do not bother writing me asking if you can review. I will ask for reviewers when I need them.

What does a tech reviewer do?

The tech reviewer reads pre-publication manuscripts and comments on them from a technical perspective. You catch technical problems or oversights in the manuscript before the book turns into dead trees.

Everything I write works in my environment. That doesn’t mean that it will work in yours. I need to know where I’ve been blinded by my environment, where I haven’t considered potential problems, where I haven’t thought of issues other people face.

You are not expected to comment on grammatical problems. A technical reviewer generally sees the manuscript before it’s been properly edited. Tech reviewers get second drafts — I write it once, go back over it to catch obvious errors, and send it on to you folks. You can expect the quality of the writing to be lower than the finished book.

Author Scalability Warning!

If you can be scared off this project, if you are going to quit on it partway through, it is in both of our interest for me to scare you off as soon as possible. Here’s my best effort at that.

My goal in writing books is to make people’s lives better. The more people act as technical reviewers, the better the book will be. I want to spend my time improving the book. If ten people review a book, and I write each one back lengthy individual letters commenting on their comments, I will never get the book finished.

Increasing the number of tech reviewers also increases the number of people I must interact with. This consumes more time. The only way I can deal with a large number of tech reviewers is to deal with all of you in exactly the same way. This menas that many seemingly minor requests (i.e., distributing chapters in plain text/OO/.doc/PS/whatever instead of PDF) will be refused because they cause far more headaches for me than the feedback will be worth.

Also, I am cantankerous, grouchy, overworked, underpaid, and antisocial. When I’m writing a tech book, I’m much the same except I stop being so friendly.

You have been warned. I recommend that you stop reading now if any of the above disturbs you.

How does it work?

First, you send me an email agreeing to not share the work-in-progress.

I send out chapters of a book-in-progress as they’re finished, or in an order that makes some amount of sense. (More than once, I’ve finished chapter 18 before chapter 2, which might mean that I sit on the later chapter until you have enough context to read it intelligently.) The manuscript is distributed as a PDF. You read it, and send back any comments you have in a separate email within ten days.

How much experience does a tech reviewer need?

Any amount. The true guru can help by sharing his wisdom.

The novice can help by saying what makes sense, and what doesn’t. My goal is not to write so you can be understood; my goal is to write so that I cannot be misunderstood. That’s where the truly uneducated most helpful.

What do I get?

Very little, sadly. Authors make slightly more than migrant farm labor, but less than purse-snatchers.

The people I ask to review are usually project members who are looking for more exposure for their project. These people view a book as promotion for their work. And indeed, I couldn’t write these books without the project existing in the first place!

Having said that, I do give credit in the book for people who return substantial commentary on all parts of a manuscript, or who return detailed comments and additional suggestions on the part that covers their particular area of expertise. Also, the publisher gives me a limited number of copies which I distribute to the most helpful reviewers.

If you are reviewing:

I distribute chapters as PDFs. I used to give people a choice of multiple formats, but this caused two problems: preparing the formats (an annoyance) and how people returned comments (a real problem). I had people returning plain-text comments amidst plain-text files, people using the “annotate” feature in OpenOffice, people sending RCS files, hand-edited PostScript, and all sorts of other methods. Aggregating all of this was a complete nightmare, and often took longer than writing the chapter in the first place! Worse, more than once I missed valuable feedback due to this melange of methods. This rightfully angered reviewers who had taken the time to make the comments, and distressed myself no less.

I frequently annotate code segments or command-line output with “numbered balls,” i.e., 1 in a circle, 2 in a circle, 3, etc, allowing me to point to exact sections of output in the accompanying text. These numbered balls appear in the MS “Wingdings 2″ font. If your system does not have the font, the symbols will instead show up as some weird character or a random letter. The exact weird character will vary depending on the fonts you have installed, your OS, and the phase of the moon. Do not let the weird symbols distress you. If you have the letter “u” appearing in front of a word, you’ve been bit by this. Rip the font out of a Windows box (you almost certainly have a spare Windows license sitting around somewhere), or just live with it.

Sections in blue are directions to the publisher’s folks, not to you. This is usually stuff like “Put figure 8.3 somewhere around here.” For my sanity those figures are usually in-line in the manuscript, but the layout folks need some flexibility on these things.

Please return your comments in boring old plain text.Yes, I know that there’s all sorts of annotation features available, lots of formatting tools that can make content more accessible, and so on. But when I have everyone’s comments, I aggregate them all in plain text.

What does Lucas do with the comments?

When I receive comments, I’ll send an “ack” to let you know I got them.

Then I wait until I’ve received all the comments on a chapter.

Then the fun begins; I sort them out. My response to the comments depends on a) how many reviewers I have, and b) what they comment on. In some cases, it’s clear that I’ve made a goof; if a clear majority of reviewers say “hey, this isn’t right” then it probably isn’t right, I’ll go on-line and start digging for information. At times this shows that I’ve touched upon a controversial subject, and that I need to present both sides of the argument or at least label it as “controversial.” I do freely assign weights to people’s comments based on their experience. The subject matter expert’s comments get more weight than the newbie’s. On the other hand, the newbie’s questions frequently show me where my writing has gone astray.

There are some things I don’t do:

I don’t reply with comments on your comments immediately. Reading criticism can be difficult, especially when I’ve screwed up and ten people scream “You’re wrong, loser!” I’m well aware of my less than absolute knowledge of technical matters, thank you.

I don’t argue that “I’m right and you’re wrong.” If you say I’m wrong, I double-check my facts and sources, and frequently change. (I’m wrong more often than I like.) If I am factually correct, but you think I’m wrong, then I probably wrote poorly and need to address problems in the text.

I write about how things are, not about how things should be. If a reader can take action to correct a problem, I’ll suggest it; if I’m writing about a flawed system I’ll take some time to discuss those flaws but not spend a huge number of pages on opting out of the system entirely. I’m not doing political writing, nor advocating armed revolution against an existing technical protocol. I’m writing about what is, and about how day-to-day network admins like myself can deal with problems and take advantage of the opportunities offered by our tools.

I normally don’t get in long discussions with tech reviewers about the reviews. The “literary energy” required to have such discussions is better spent in improving the book.Yes, this process is not fun. In fact, the word “sucks” comes to mind. But it’s the only way to get a community-reviewed book done, and community review is the only decent, sensible way to write a book about any open source project.But, by sending me useful, correct, thoughtful comments about a book, you have the pleasure of disproportionately increasing the amount of suckage in my world by doing nothing more than sharing your wisdom and experience. How can you possibly resist?Thanks for reading this far. If you’re still interested in reviewing a book that I have announced I’m seeking pre-pub reviewers for, please send me an email stating that you won’t share the pre-publication manuscript.