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

This entry was posted on Sunday, September 8th, 2013 and is filed under books, language. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.