Stoyan Stefanov

Personal blog

 

Technical writing checklist

update: added "can", "in order to"

Working on a first draft should be quick and dirty. Then comes editing. And at the last stage, right before you're ready to send the finished manuscript, how about a checklist? A lint, if you will.

Starting the OOJS second edition I took note of my common mistakes. I came up with (and kept expanding) a checklist of last minute sanity checks that I go through before sending each chapter to the editor. Just when I think I'm ready I search for each string in the document and address potential issues.

The big picture items:

  1. Technical writing should be precise and correct above all else. Weak and ambiguous words such as "may" or "some" must go
  2. Cutting out filler words
  3. Avoiding common mistakes, e.g. "its" vs "it's"

Here's my checklist with my common mistakes. Feel free to customize for your own writing.

JSLint

Since I'm writing about JavaScript, JSLint (or JSHint) are constant companions. Consistency (semi-colons, spacing) helps the reader focus on important things. Plus, sloppiness in any form has no place in technical writing.

"very"

Filler word. Delete.

"basically"

Delete.

"actually"

Most likely not needed.

"pretty"

Doesn't help the prose, delete.

"easy"

Don't say it's easy, show and prove how easy it is.

"useful", "interesting"

Same as above. Prove it. Why is it interesting? When exactly is it useful? It's not enough to be useful just in general, because anything can be useful eventually.

"its" vs. "it's"

Common mistake. Go through and make sure it's the intended use.

"than" vs. "then"

Same thing. Search the chapter for each instance and read the sentence once again.

Shorten "it is", "you are", "you will"

This is my British publisher's issue I think. As far as I remember they changed all of these. No need. These are longer and make you sound pompous.

"way to"

Can often be removed

"we", "our"

It's all about the reader. The word is "you".

"I" can be used but sparingly. Say, 3 times in a book.

"We" sounds like "me and the crown" (this is from Packt's guidelines)

Arguments vs. parameters

Commonly mixed. It's good to be precise. Wikipedia.

function sum(a, b) {
  return a + b;
}

var price = 100, tax = 20;
sum(price, tax);

 

price and tax are arguments passed to the function sum(). And a and b are the (formal) parameters that the function sum() accepts.

"some"

Which? It's hand-wavy.

Searching for "some" also matches "sometimes", which is no good either.

"will"

(Got this from Steve Souders' reviews of calendar articles.)

Stuff is happening now. It's here and it's concrete. "will" makes it sound like it may not happen.

"The result will be..." -> "The result is..."

"may", "might"

May or may not? Weak. Ambiguous. Gone.

"probably"

Hello, technical topic here. It is or it isn't. No wiggle room.

AJAX -> Ajax

Way past the initial excitement.

"jQuery", "YUI"...

Avoiding references to current topics and events in a feeble attempt to write "evergreen" books (as if it's even possible for a computer book). Any time-sensitive info comes with "at the time of writing" disclaimer.

"can"

"Can" is weak. Doesn't mean anything. Of course you can.

"you can use" -> "you use"
"can be" -> "is"

"In order to"

Filler. Shoot at sight.

"in order to" -> "to"

Update: http://matt.might.net/articles/shell-scripts-for-passive-voice-weasel-words-duplicates/

Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Powered by WordPress, theme by ♣w3clubs.com, based on Kubrik and Sancta Simplicitas