When writing a technical book there are a few steps involved. Sure, I’m writing the text, producing the images and the code. But after that… the reviews come.
The first one is the technical review, if I am lucky I get Manuel Jordan, that is very scrupulous and very technically savvy. And he misses nothing. He corrects typos, code, asks questions and proposes changes that increase the value of a book. I’ve had other reviewers and they were not even a quarter as good as he is. So I began asking Apress for him as a reviewer for any book I write.
After Manuel is done, and I modify the chapters accordingly the grammar/expression review comes in. This is supposed to be performed my very good English/American language speakers that sometimes also use software to replace certain expressions. Reviewing my books after they do their work is the part I loathe the most. Why? Well, because they are probably not technical persons and because that software sometimes does shitty things, that they fail to notice. Also the final review that I have to do has a very tight deadline, although I have a full time job. When it comes to this review, nobody seems to care.
Anyway, this year I decided to show you a few samples of how my last review goes. So, I receive a PDF that is full of notifications regarding what was changed and with paragraphs highlighted in red, when they seem to make no sense. Every team or person that makes these reviews have their little peculiarities. In one of the previous books somebody replaced all instances of which with that. In the book I just finished reviewing these guys did the opposite. In the previous book, one of these persons modified all the tenses of the to be verb to present tense. As you can imagine, I was not happy about it and had to review a 700 page book in a few days and correct the damage.
Seriously, I now have the impression that the grammar review is done to force me to read my own book. Because this review does the following:
- messes up technical definitions
- messes up some of the images by resizing them in the weirdest ways
- splits up big phrases that make sense into smaller phrases that make no sense
- sometimes fucks up correct grammar
- and although there is a team of people doing this, they still managed to miss typos
- and they missed LaTex formatting elements too
Anyway, do you want read more about my own personal 4-day hell? Here we go:
-
Apparently somebody in the team doing the review does not like the etc shortcut. Because it was replaced every where with and so forth. It’s not problem really, but it kinda adds 3 words to the book instead of one. So if the purpose is to keep the book smaller, to be (ahem!) transportable, they’ve failed.
-
Every time I introduce a piece of code or configuration, I introduce it with: You can write code like this:, or The resulting code should look like this: , etc. They hate the like this expression too. Because they always replace it with like the following. This is not a biggie either, I guess in their heads sounds more official or something, and it does not affect the technical meaning so I accept it.
-
Because the publisher is from the US, they do not like it when I use the word behaviour, because they always change it to behavior.
-
Sometimes they change words they do not recognize… just because. Somebody changed iBatis to bates, yes, like Norman Bates from Psycho.
-
Sometimes they delete the first piece of a phrase just because it mentions something from the previous section of chapter. I usually do that to continue the idea or compare it to something that I am about to introduce. Or they decide to split big phrases in smaller ones. The big ones make sense. The smaller ones, not so much. And before correcting their stuff, sometimes trying to keep the split phrasing, I just have to vent writing comments like these:
Of course I delete them before I send the final document and for the moment it helps to release the stress. -
All phrases containing any forms of [is|are|can be] used to [create| make | build] were modified to: creates, makes, builds. This has lead to the technical meaning of some things being totally trumped up. Forget about grammar being affected, the technical meaning is the one I am concerned about.
I also have a more easier to read example:
Microservices are a specialization and implementation approach for service-oriented architectures (SOA). They are used to build flexible, independently deployable services.
became
Microservices are a specialization and implementation approach for service-oriented architectures (SOA). They build flexible, independently deployable services.
Say what? Who does the building, the microservices? Really? How? Do they use bricks? In defence of this team, after each [is|are|can be] used to [create| make | build] I should have added [by X], where X can be the Spring Ioc Container, the developer, god… you know, the one performing the action. Because apparently when we say metal is used to make cars, it just does not make sense without mentioning who does the making.
Also, I can’t understand the logic of these persons. If you have doubts just imagine the construction used in a daily, human phrase. Flour is used to make bread is not the same with Flour makes bread. The first makes sense. The second doesn’t.
- Sometimes they take expressions like it is used, it is created, it is mentioned and just remove the it is part. No idea why.
Yeah, so this was my life starting Tuesday until one hour ago when I sent the corrected PDF back to them. Finally it is over (theoretically). The book, Pivotal Certified Professional Core Spring 5 Developer Exam (I still do not know who came up with this name), is done and I can finally sleep. Maybe.
Stay safe, stay happy and stay in bed!
