First Draft Review of Technical Writing...

I capture a few common traits among almost all the articles and books I've reviewed. Note that I consistently do ALL of these things on my first drafts, and so does nearly every article I ever read in draft form. Save yourself and your editor some time and scrub this stuff yourself. These are just some notes I wrote for myself and want to keep around for later reviews.

The single most significant common mistake in all level engineers technical writing by 90% magnitude over anything else I ever review:

common comma problem: you can get rid of the comma by swapping the two phrases that make the sentence. it usually reads remarkably better when you do this. this is a result of writing it how you think it. this doesn't flow as smoothly and is not an email or blog entry which vary in expectations of quality.

this is, by the way, probably my most significant issue, as well.


Too many commas: two phrases joined together by a comma. common thing to happen: comma isn't needed at all (therefore, if it can be read without it, get rid of it for simplicity). Agh!!

space is required between references and text next to references: foobar is a good candy bar[xxx99] should be 'foobar is a good candy bar [xxx99].

periods at the end of a reference in your references section. i don't know why, we all always miss these. in fact, in the GUIDELINES for the book we're currently writing some of the example references were missing periods. agh!


[foo99] authors. title. more info

should be:
[foo99] authors. title. more info.

I realize you might find a strunk and white like book that says the first is acceptable. its wrong, its not elegant, its not clean, its ambiguous if you have some that can end in a period, and some that don't.

english writers not writing american: not a read issue, but in general striving for consistency in a book we want all words to be spelled consistently. i'm not claiming one is more correct, i am simply saying consistent:

synchornisation should be syncrhonization.
initialisation should be initialization.
(ed: thanks to jake for pointing out typo in original posting for initialization.)
zed is z.

figures are not mentioned in text, this is not proper technical writing. All figures should be cited somewhere in the text.

figures are not numbered correctly (embarrasing).

writing like its a conversation in prelude or prologue, especially at the end of a paragraph or beginning of a paragraph.

the article) : 'now, just bang out a the piece of code and we are done'. 'a bunch of functions just need written up, and you are done'.

Mostly, I wanted to capture this stuff, so that I don't do it myself ever again[lake07]. :)