After the Deadline

Re: Writing Great Technical Documentation

Posted in Talking to myself by rsmudge on November 13, 2009

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.

errorss

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

2 Responses

Subscribe to comments with RSS.

  1. Jacob Kaplan-Moss said, on November 13, 2009 at 7:24 pm

    Thanks for the feedback, Raphael. I’d not seen “plain english” before; that’s a neat resource.

    For the record, it’s not that I’ve “omitted” proofing software: so far I’ve deliberately avoided talking about software. It’s easy to look for technological solutions to our problems, but no level of software can compensate for not knowing how to write. After all, if you don’t have a grounding in style, how do you know when you’ve got “too much” passive voice, and when it’s “no big deal”?

    I *will* be dealing with tech in a later post (or maybe a couple; I’m not quite sure); After the Deadline’s certainly on my list 🙂

    • rsmudge said, on November 13, 2009 at 10:44 pm

      Hi Jacob,
      I credit you for writing a great series and getting people talking about this topic. I used to work as a scientist and part of my job was writing technical reports. We were instructed to use clean and concise style so I knew about avoiding passive voice, hidden verbs, and fluff phrases.

      I discovered Plain English later and felt happy to see a label I could assign to the concept of “write simply, so your reader can understand”. It’s good stuff.

      I look forward to seeing your post on technology. If you want a pointer to some tools to look at, let me know. There is a lot of product innovation happening in this area because processor power is cheap now and data is readily available. Unfortunately a lot of these innovative products are proprietary but it’s still neat what’s happening.

      — Raphael


Comments are closed.

%d