One of the most essential parts of producing a great technical article, blog, or even a book, (referred to from now on generally as a work) is having someone who can check your writing and make sure it is right. You can do a mediocre job with grammar, punctuation, etc. and still produce technical resources that people can get value out of. But when technical details are wrong…it is actually possible that a reader becomes less knowledgeable by reading what was supposed to be a technical resource.

In this blog, I want to put out a few guidelines that I use when am a technical editor for some piece of writing… sometimes even my own. Usually this kind of task will be done on non-academic work, sometimes called trade publications. There will be very  little new ideas put forth in the writing and the usual point is to take what can be a complex topic and simplify it for the reader. As such, it is not atypical that the writer is actually less knowledgeable about parts of the topic than desired. I know in the first version of my Database Design book (on version 6 now), I did a reasonably bad job of understanding some topics (both before and after the tech edit phase). The book overall was pretty good, with the help of some really good tech editing, but even today I have had a comment or two from academics on how my book doesn’t quite get it.

Let me clarify one point a little before proceeding with a few guidelines. I did say “even my own.” When I write a blog, I don’t have a tech editor, so I have to put a little space between myself and the writing and read the material a few times and say “is that really right?” Usually I am (and usually most writers I have worked with were too,) but usually isn’t the target. If I can’t say 100% in my mind that something is right, I still look it up.

The general process of doing a technical edit for a computer book, for me has been this:

• Scan the document, to get an idea of structure
• Read the material with a suspicious eye, like you think the author of the writing is dumber than toast. It is easier to do when it is your own work, admittedly.
• Execute every piece of code, build every VM, set up everything that is described (To your limits)
• Comment (usually in a Word document) on everything that doesn’t work
• Comment everywhere you disagree technically
• Give ideas on how to make the piece of work better
• Give feedback on how things are good

It can be a daunting task and not everyone wants a tremendous amount of feedback. Ok, no one WANTS a lot of feedback, but I know I personally am more afraid of 0 comments than I am of 100s. The following are tips I suggest people consider when they are tech editing, as much as possible:

———

Be nice – I want to start here because this can be the hardest thing. But I have heard many times from an author “thank you for the nice comment”, usually because I was tearing up the rest of the work. If you have major concerns, pointing out what is working is a great idea. (Ideally not in one of those “yeah, this is great, but actually it is not” sort of ways. Fake niceness is, to me, worse than just getting told I am doing a bad job.

Be nitpicky – The whole job is really just being nitpicky. Like really nitcpicky. (Comment: not how nitpicky is spelled) (Comment: Good point, but while being annoyingly nitpicky is a lot of the job, it really isn’t all of it. Should probably be “Most of the job…”) (Comment: check with your author/book publisher to see how nitpicky. Sometimes the target audience is important to the level being targeted. Still, right is right and wrong is never right.)

No seriously, niceness is important – Because all that nitpickiness really builds up. Most technical authors probably have experienced some serious anger/anxiety/etc from a bunch of tech edits. When you finish working on a piece of work after a tech edit it is a great feeling, and usually I look back and say “That was great! Thank you tech editor”.

Along these lines, I would generally say not to be repetitive. If the writer says something wrong repeatedly, after a few times, maybe just note that it is repeated if it is clear enough along. Not only does it start to hurt, but it gets in the way of finding other stuff.

I like it when people are verbose and offer suggestions – Say I wrote “the sky is blue”. A comment might be, “not clear, explain.” Or it could be “This isn’t clear because I am not sure when you meant. What if you said ‘The sky is blue during clear skies because of… ‘ and then explained.” When the project is nearing the end, if the comment is unclear, it is probably ignored and you probably had a good point.

Suggestions may or may not be welcomed by an author. Don’t take it bad if you are involved in a second tech edit to see comments like “this is my book, that is not what I am doing”. You may not be the tech editor for that author in the future :). 

I feel like this is part of the value you provide as a tech editor if it is desired by your author. I like nothing more than to get back a chapter with lots of suggestions as to how to be more clear, or more right. Not everyone agrees and what makes your job “good enough” is a complex topic!

Make sure you KNOW you are right or make sure to note it as such – When you are going to tell the writer that their work is wrong, make sure you can back it up. When editing something I don’t really understand, I do searches for keywords found on the web. If I don’t see it in a few places so I am sure something is wrong,  I tend to say “I think this may be wrong based on ‘sentence from a document’ linked here: https://somewhere” or sometimes just from my memory (which I will also note!) Obviously a great technical document can be backed up with lots of external documentation, most of which you won’t be linking to or citing (unless this is actually a new idea and proof of that idea… which is not typically what I am talking about here.)

Make (at least) two passes through a document –  Start out skimming the work as much as is reasonable, looking for the topics covered. As the technical author, you might suggest that things are out of order, but the worst feeling is spending 10 minutes explaining how something needs to be said, only to find it a few pages later. Done this many times. Many.

Be as thorough as expected, but not too much more – It is not your work, and your name will probably just be a brief footnote in the book, but I try to think “if it was me, what would I want”. Nothing makes me more unhappy than to find glaring errors in a piece of work that supposedly was checked over. I don’t expect perfection, and I definitely don’t deliver it, but if I have written 10-1=0, I hope that is caught even in a casual read.

(My theory on how I miss such simple stuff in my initial submissions is that as an author I have read and modified parts of the material 5-20 times and I get blind to parts of the document. Seriously start to hate every word you have written until you can be away from it for a few weeks. When you are tech editing, you generally only want to make two passes and not get that connected to the work…though that is not always possible.) 

If something smells funny, check it out – Authors at times forget the lessons of high school English: “You have to write your own material.” In the real world the rule is more “You need to produce original material.”

Sometimes it can be a ghost writer situation (having someone else write for you may or may not be allowed) that causes it to seem like 2 people wrote something. But when this is the case, it is essential that the publisher is okay with multiple authors.

The other thing to look out for is plagiarism. Even if the publisher allowed for multiple people working on the work, the other writers need to have authorized the usage. Copying and pasting from random websites is often caught by pasting sections of text into a search engine.

On more than one occasion I have searched for a sentence to find large amounts of material from a vendor’s documentation repeated exactly in the text. Best case it was unintended. Worst case it gets through and the original work’s author sues the author (and probably only the author…read your writer’s contract, they make that clear!)

Don’t change the source material unless authorized – When I do my own tech editing, I change the text as I find issues. I really don’t like changing other people’s work, and I don’t like mine changed either (unless it is a work for hire and the person paying me makes the changes…It is essentially theirs anyhow. Posting suggested changes into comments puts the onus on the writer to agree without looking through change tracking.

NEVER change a document without change tracking/commenting – Even if authorized to make changes, even if you are the technical editor for the book/website, even if it is the simplest of things. Make sure the original author can see what changes have been made.

——-

This is just a few notes on what I like to do as a technical editor, I might add to them later, but the gist of it is this. If you are technical editing a piece of work, your job is to improve the technical correctness of the work some amount. This may just be a quick overview of the work, and it could be a line by line correction of every little issue.

Discuss how deep to check correctness with the people you are working with, possibly the author or book’s editor before you do too much or too little. I personally prefer to almost prove that everything stated in the work is correct if I can, but that may not be what you are requested to do.