After the Deadline

Jacob Kaplan-Moss has a great series on his blog about writing technical documentation. You can imagine this is a topic near and dear to my heart. He starts his series discussing what to write, technical details of writing, and continues it with a post about needing an editor.

His advice is great, but despite this I feel proofreading software was wrongly omitted from the discussion. The ideas are sound but instructing readers to look to the Chicago Manual of Style for specifics isn’t helpful. This creates a high entry barrier for those who want to improve their writing.

On technical style Jacob talks about many good principles that are popular in Plain English. He says to write short paragraphs, keep a conversational tone, omit fluff, and watch out for the passive voice.

One commenter mentioned that beating up on passive voice and telling writers to omit fluff is useless advice on its own. From a blog post how is the reader supposed to know what is considered fluff?

For these problems there are software style checkers. A style checker is (usually) a rule-based tool that looks for phrases editors get nit-picky about. It’s not the same as having a human editor but checking your writing against thousands of common pitfalls doesn’t hurt. In the UNIX world we’ve had GNU Style and Diction for many years. You can also use After the Deadline. For omitting fluff it finds complex expressions, redundant phrases, and clichés. For most things it flags it offers a usable alternative. For example, used is suggested for utilized.

There is nothing wrong with passive voice on its own. Use passive voice to downplay the actor who performed the action. The danger with passive voice is overusing it. Again, a style checking tool can flag your passive voice. If you see it in every sentence, you have a problem. If it’s a rare occurrence, no big deal.

The last post in the series talks about the need for an editor. Jacob’s first tip: don’t edit without permission. I have mixed feelings on this. I get edits in my email with a respectful tone, this is fine. And then I get those with a smug twist and that bothers me. The key is to be respectful. If you want to invite edits to your blog, consider a tool like GooseGrade. It’s a widget that invites your readers to notify you of typos and their relevant correction. GooseGrade has an interface that lets you accept these changes into your post with the push of a button.

I like Jacob’s tips about printing your document and editing it with a red pen. I do this when I’m editing an article and feel the extra attention to detail is worth the time. I also recommend reading backwards through the document. That helps me.

Jacob has a few typos in his third post. ‘You’ll be less likely to “know” that you got something write,’ is called out in the first comment. When I am tired, I mix up write and right. I do this all the time. We can’t expect a human editor for everything we write, but a mechanical check is always possible.

Spell checkers have a bad rap because most only flag an error if what you wrote happens to be missing from the dictionary. Fortunately these tools are evolving. The newest ones look at context and use statistics to detect misused words like right and write. After the Deadline has this feature.

The principles Jake discusses are good to know and readers will benefit. For the low-level details of some of these, there are software tools that can help you. As you’re writing documentation, I urge you to find a tool that works for you and add it to your process.

After the Deadline is an open source proofreading tool that checks spelling, style, and grammar. If you’re a developer you can embed it into your application. Plugins for jQuery and TinyMCE are available. You can try After the Deadline at http://www.polishmywriting.com