Stoyan Stefanov

We need to talk.

Background

I'm a technical author. I write books about programming. I don't speak or write proper English. Not my area of expertise. I need your help. But, please, don't overdo it. Here are some Do's and Don'ts that will make our life together easier.

DON'T use Word

Stop it. I know it's not your fault but try to change this within your organization. Technical people are lucky to have discovered the beauty of source control. You know, Git, SVN, that sort of thing. Technical books should be written like programs, using plain text (asciidoc, markdown). From there you can generate epub, mobi, pdf, html whatever (lookup "pandoc"). If you're not familiar, source control is like "track changes ON" in Word, only infinitely better.

DO track your changes

Giving me a word doc changed beyond recognition with no way to quickly see your changes and no way to quickly undo what you messed up is criminal.

DO help me make my prose shorter

Delete, delete, delete! (with track changes ON, of course)

DON'T add verbiage to my prose

See above.

When I see changes like these, I want to chew my leg off and run away from the project:

ME: A number of events reshaped the web development landscape in a positive way: [list of stuff]
YOU: A number of events reshaped the web development landscape in a positive way. Some of them are given as follows: [list of stuff]

"As follows"? Search and delete all your "as follows". We can all see it follows.

ME: The cat has certain characteristics (color, name, weight) and can perform some actions (meow, sleep, hide, escape).
YOU: The cat has certain characteristics (color, name, weight, and so on) and can perform some actions (meow, sleep, hide, escape, and so on).

The golden rule: remove, do not add to the text.

DON'T remove my emphases

I use italics when I try to emphasize. This is because I can't make sense of your multiple custom formatting styles (italics, emphasis, bold, keyword, term) in your custom .dot templates. But you know your custom styles. Use the right one. Don't just remove my formatting and de-emphasize the text. It dies a boring death!

ME:
A regular expression consists of:

• A pattern you use to match text
• Zero or more modifiers (also called flags) that provide more instructions on how the pattern should be used

YOU:
A regular expression consists of:

• A pattern you use to match text
• Zero or more modifiers (also called flags) that provide more instructions on how the pattern should be used

DON't capitalize my "boolean"

Word auto-correct does it. Ditch Word. New words get special treatment initially. Then they integrate into the common language. E.g. "Web Sites" -> "web sites" -> "websites". The word "boolean" is common in programming.

ME: "numbers, strings and booleans"
YOU: "numbers, strings and Booleans"

Yuck!

DON'T just "fix" stuff

Don't reword my prose. If something's sounds off, tell me in a comment. Ask clarification. Suggest a better wording. Don't just fix it.

Otherwise we end up with nonsensical gems like:

ME:
The regular expression objects have the following properties:

• global: [...snip...]
• ignoreCase: Whether the match is case sensitive or not, defaults to false.
• multiline: Search matches that may span over more than one line, 
defaults to false.

YOU:
The regular expression objects have the following properties:

• global: [...snip...]
• ignoreCase: When the match is case insensitive, the defaults to false.
• multiline: Search matches that may span over more than one line default to false.

Rule #1 in technical writing: above all, be technically correct!

DO let me be human

I have some way of saying things. Many people seem to like it. Let me sound like me. Even if it's not the proper Queen's English.

ME: The function F contains the variable b
YOU: The F function contains the b variable

Err, no!

Less is more

Thank you for your understanding!

In conclusion, the top 3 tips for our happy relationship: are given as follows:

1. Fix my punctuation, I know I suck at it
2. Suggest lots of deletions to help make the prose compact (we all suffer from wordiness)
3. Comment on my nonsense, don't fix

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/

From The Elements of Style's chapter on Misused Words and Expressions:

-oriented. A clumsy, pretentious device, much in vogue. Find a better way of indicating orientation or alignment or direction.

They suggest instead of

It was a manufacturing-oriented company.
Many of the skits are situation-oriented.

it's better to say:

It was a company chiefly concerned with manufacturing.
Many of the skits rely on the situation.

So for the second edition of "Object-Oriented JavaScript" should I suggest to the publisher the title "JavaScript chiefly concerned with objects" or "JavaScript that mainly relies on objects" or maybe "Programming with the JavaScript Language while Mainly Concerned with the Use, Nurture and Care of Objects":)