I’ve been lucky enough to have gotten to tech review a number of Mac and iOS programming books. I find the process very enjoyable, if a bit time-consuming. I assume I do a decent job because publishers and authors come back to ask me to review subsequent editions of books, or entirely new books.

Why?

From the foreword I was invited to write for Learn Cocoa on the Mac back in 2010 (which I also got to review):

Just think of it. You get to read a nerdy book before it comes out. You get to learn cool new stuff along the way. Best of all, you get to poke holes in the text and code, kibitz and generally make random suggestions. And then you don’t actually have to do the work involved in fixing it!

That sounds like the ideal job.

What?

So, what’s involved in technical reviewing? You basically get a stream of chapters as they’re written. You read them, digest them, and offer feedback on how to make things better. As far as I’m concerned, my first job is to make sure the readers get good, solid, correct information. My next job is to make sure the authors look awesome. There’s not much more embarrassing than committing some howler to print, haunting you til the end of your days (or at least until the next printing).

The actual tech review workflow depends on the publisher or group you’re working with. Some publishers use Word and pass chapter files around or use a centralized mechanism like SharePoint. You’d use Word’s commenting features to make your notes and suggestions. Others pass around PDFs, so you can use your favorite PDF reader to add comments. And sometimes you might have access to the git repository for the book materials and you’re told to go fix things yourself.

Feels like the first time

I try to read the materials as if it was my first time encountering the material. Will the expected reader have this knowledge or this skill? Or will they need some hand-holding and explaining. Is the level too high or too low for the target audience.

If the book is talking about base-plus-offset pointer math to simulate a two dimensional array with a dynamically allocated block of memory in Learn Programming For Fun!, you may be targeting too advanced of an audience. On the flip side, if the authors are saying “loops are cool!” and talking about basic looping structures in the fourth edition of Advanced Embedded Processing for Nuclear Medicine : The Big Nerd Ranch Guide, they’re probably targeting too low of a level and will disappoint their true audience. The author can add an aside, or a “Tech Block” to elaborate on a particular issue.

This involves figuring out the assumptions the authors are making, and if those assumptions are appropriate. An author may be proficient in Photoshop, but most readers won’t be able to “Just open photoshop and create an icon for your app”.

Get the Holistic Picture

You’ll usually get the table of contents, so you know how the book will be organized. The actual chapters will come out of order. As you read through several chapters, you can build a picture of the whole book. From that you can figure out the assumptions the authors are making. You can also see places where authors are going on tangents that will be covered later. “You’re talking a lot about UIImage in chapter 3, while you’re dedicating all of chapter 9 to UIImage. Will there be redundant overlap?”

One thing I try to keep my eyes out for are forward references. Like forward references in code, these are the statements that say “We’re not going to cover this here, but in some future chapter”. A couple of those are OK, but I have read some books where the first half felt like nothing but forward references. You have to slog through a lot of promises before you get to the actual new and interesting content. If it’s looking like the first part of the book is mainly referring to the second part, you should have a chat with the managing editor to see if things can be reorganized before it’s too late in the production pipeline.

The in-the-trenches work

The majority of your time will be reading the text of the chapter. Most books these days have a tutorial component (click this, override that, implement some other thing), so it is important that you do all of these steps, with a critical eye out for errors and possible improvements.
I always copy and paste the code. I know my learning style and, and I learn more when I type stuff, but I’m not here to learn (that’s just a happy side effect). I need to make sure the code compiles cleanly. If I type it, I’ll unconsciously fix errors in the code while introducing my own. More than once I’ve encountered code that looked ok, but wouldn’t compile because the authors changed the name of a variable in one place but not another.

Sometimes code doesn’t copy and paste cleanly from a PDF. You might have to ask your wranglers for the original source documents. And be aware that copying and pasting into Xcode can lead to error reports being on the wrong line:

You can see that the error is on the next line, but Xcode is showing it on the line above (sometimes it’s displaced several lines), and the highlighting for the error region corresponds to startPoint on the next line. (rdar://12572974)

What to fix

Your job isn’t to fix language – publishers have editors that do that. I do sometimes fix egregious mistakes in the Word file, such as misspellings and misuse of it’s. But the main job is it to make sure the code is good.

There’s two classes of things that make code good in print – it’s correct, and it’s stylistically consistent.

Inconsistent code style in a book drives me nuts. Sometimes the brace is on the same line as the if. Sometimes it’s on the next line. Sometimes it’s two space indents, sometimes it’s four. Sometimes it changes in the same method body! I don’t care what style the author uses (or a group of authors use), so long as it’s consistent. Inconsistent code presentation is sloppy, and so I have to wonder if the authors are that sloppy with their code, what else are they sloppy about? Usually my alter ego Captain Retento makes the comments “Captain Retento says that the first half of the chapter had spaces after commas, and the second half doesn’t.”, since it’s not a correctness issue.

The only stylistic thing I recommend to authors is to use more horizontal whitespace. Print is usually black and white, and if you typically only use code colorizing to discriminate parts of an expression, they can become hard to read in print without spaces. I find something like

for(i=0;i<5;i+=sin(x)){

to be much less readable in print than

for (i = 0; i < 5; i += sin(x)) {

There’s frequently plenty of horizontal space for expressions to have some readability spaces there. Noneedtoconservehorizontalspacesobenicetoyourreaders.

Correctumuno

And then finally, making sure things are correct. One of the reasons (presumably) you’ve been brought on board to tech review is because you have some domain knowledge. Or if you don’t, you know how to interpret available materials to fact-check. (Another reason you may be reviewing materials is to just get the perspective of a total newcomer. The expectations should be made clear before you start working.)

As I’m reading the prose and the code, I compare it to my mental bank of trivia. Is this statement correct? Is it accurate and relevant to this discussion? Is it up to date?

When I get that “huh, that’s interesting, but it doesn’t sound quite right” feeling, I go check my usual sources of information: the headers, the docs, Uncle Google. I might ask a quick question of a friend or coworker, or make a quick one-off program to verify.

For iOS books, especially new editions of older books, you need to be up to date on mutations in the API. For example, iOS 6 has deprecated viewDidUnload, which typically got lots of love and attention in books that covered earlier versions of the OS. If the iOS 6 version of the book still gives it lots of love and attention, then you make a comment that they need to fix that.

A quick skim through the release notes can plant that info into your brain, and I also keep the headers handy. Apple has nice markers for information like that:

- (void) viewDidUnload NS_DEPRECATED_IOS (3_0, 6_0);

That says that this call was introduced in iOS(iPhoneOS) 3.0, and deprecated in iOS 6.0.

At the End

I read through all my comments when I finish with a chapter. Sometimes I’ve made a comment “I don’t understand this – maybe mention NSFooBlarzle’s involvement in this process”, and then a page later it gets explained, and the flow of prose makes sense.

Sometimes (more times than I’m willing to admit) my comment makes no sense and needs revision. That’ll save you, and the authors, some time going back-and-forths. “What did you mean by Verify a the perhaps at runtime?” I also put a comment at the top of the chapter with a brief overview. “Great chapter, just a couple of nits. Be sure to check out the code sample, there’s a variable name that didn’t get changed properly so it doesn’t compile.”. If there’s something terribly bad, like gross misunderstanding of the material, you might want to have a chat with the managing editor.

So that’s what goes through my head when I’m doing a technical review for a book. It’s work. A lot of work. Not as much work as the writing, but still evenings and weekends can disappear. Some publishers pay reviewers by the page, some a fixed stipend for the book. There may be other compensation mechanisms I’m not aware of. Like most things involving writing, you’re definitely not doing it for the money. But it can be a really rewarding thing, seeing thank-yous in the acknowledgements, and knowing you’ve helped out the industry by bringing out a good product, and helping out the authors (many of which have gone on to become friends) personally by watching their backs.