Sunday, 6 August 2006
09:39 AM
I was chatting with one of my writers the other day, who suggested that writers feel thwarted by corporate standards for technical writing. People would rather read a blog entry than a page on MSDN, he said. The writers -- or this writer, anyway -- yearn to write "friendly" documentation that sounds more like blog entries and less like, uh, documentation. As he put it, they want to write docs that have a little more personality.
Everyone knows that after legal documents and government publications, technical writing is about the driest kind of reading there is.[1] Who hasn't heard (perhaps said) "I read this stuff when I have insomnia!" And it's not exactly a challenge to find a piece of technical writing that isn't just boring, but outright incomprehensible, even to people who should know what it's talking about.
It's not as if technical writing can't have personality. Anyone who's dabbled in Ruby knows about why's (poignant) guide to Ruby and its famous cartoon foxes. In "a funny manual that works," Gordon Meyer recently noted that "it's very difficult to use humor effectively in technical documentation," but he calls out some examples by David Pogue and Bill Bumgarner where he thinks they've done the trick. I have my own favorites. As I've noted before, a book that had a big influence on me is John Muir's classic How to Keep Your Volkswagen Alive ... A Manual of Step by Step Instructions for the Compleat Idiot, which for all I know spawned the whole notion of "idiot's guide" documentation. A sample that I cite from my famously imperfect memory: "The slow progress that a Volksie bus makes in the mountains means just one thing: leave earlier." Although most people don't think of it as such, The Joy of Cooking is another technical manual that overflows with personality.[2]
So what's the deal? Why is most documentation so boring?
Well, let's have a think. Documentation starts with the disadvantage that it's stuff that no one wants to read in the first place. The best kind of documentation is the kind you don't need at all. Documentation is part of "Job 2," as they say; most people are using the docs (or software) to get something accomplished in their real job. Why is the documentation for a photocopy machine so frickin' useless? Because everyone thinks that using a Xerox machine should be as simple as pushing a button, and having to read something just to get a stupid copy ... well, you can imagine the frame of mind in which the user approaches the task of reading the docs.
Then there is the fact, sad but true, that not every writer can write with personality. The reason -- or one reason, anyway -- that there aren't a lot of funny technical manuals is that few people can write funny to begin with, and fewer still can be funny and know something technical to write about. (If you doubt this, try it: pick something that you know pretty well and write some funny documentation for it. I'm serious about this -- if you do, send me a sample and I'd be happy to talk to you about it and if you want, share it with others.) The notion of personality in docs encompasses more than just being funny, but I'll stand behind my assertion that it's harder than it looks to write accurate, useful docs that also have some of this personality stuff.
Everyone will point at blogs and say "See? There's some damn fine writing!" Yup. I read many of them myself. But blog writers do what they want when they want, and banging out docs rarely affords that luxury. It's hard to sustain that approachable blog tone when you're writing hundreds of topics to deadline.
As a side observation, I offer that documentation with humor is refreshing, but a little of that goes a long way. Even if it were possible to write all documentation that way, I suspect (or anyway, the writing profession at large maintains) that when it's crunch time for your project, it's all, like, enough with the laffs already.
There are other reasons why docs are comparatively bland. Most documentation (as opposed to books) is a team effort, and there's a general belief that a doc set from a company should have a uniform tone. This is an arguable point, and I won't argue it; in fact, the plethora of blogs and whitepapers suggests that people by and large don't care about uniformity. Until they do, such as in API docs, where jocular, personality-laden information tends to be a lot less welcome. Tell me the syntax already, would be one way to characterize API doc readers. (See "Xerox machine" above.)
One of our writers recently did a presentation on documentation for various open-source products. Ruby was one; PHP was another. He had various observations, but one I found interesting was that open-source documentation is often written in one language only. (Guess which.)
Our docs are localized into a minimum of 8 languages. (I can never remember the actual count. 8? 12? 27?) Consider the challenge of writing docs that will have the same personality in 8 languages. Does your humor translate? (No.) Do your examples cross cultural boundaries? Is the tone that American readers find engaging equally engaging to readers in Germany? Japan? Egypt? China?[3] How do people in those countries react to poignant foxes with a fondness for chunky bacon? Hard to predict, innit?
Localization therefore imposes some cultural constraints on how much personality we want to inject into the docs. It also imposes some purely technical constraints -- we use so-called machine-assisted translation, in which software does a kind of initial pass. To make this process as successful as possible, we follow certain guidelines, which call for consistent verbiage, unambiguous words and constructions, straightforward sentence structure, and reasonable sentence length.
These guidelines help translation and they help "ESL readers" -- readers for whom English is a second language. Turns out we have users in many more languages than those we localize to, or that some people just don't have access to the localized docs. But really, documentation that's written in a consistent, straightforward way actually benefits all readers. (Compare those legal and government docs again.)
I'm going to go out on a limb here and suggest that a lot of documentation is pretty well written and is perfectly fine to read, considering. It's clear; it's concise; it gives you the information you need with a minimum of fuss, especially when you don't have time for, or are not in the mood for, a little technical comedy. I won't make this claim for most documentation; the ratings we get from MSDN prevent me from making a blanket claim. But some of the docs get very good ratings, which is of course mostly that the information is great, but is at least partly for the reasons I cite. They're docs that present the smallest possible impediment between your problem and the solution.
So, where does that leave us? Does documentation need to have more personality? I'm all for that, as long as we can work within the constraints that I listed before. Does that mean docs have to be awful? Hardly. I've noted before that the Windows people have guidelines for the "Windows Vista Tone," which attempts to humanize the UI by being more conversational. If they can do it in the UI, we can do it in the docs.
What I think, though, is that we would not see some radical overhaul of the docs. I proposed to my writer that the difference between what he imagines as documentation with personality and some well-written existing documentation is not so great. By the time you've written docs with personality that can also be translated and are readable for ESL readers, you've got something that's probably not so far from a lot of the docs we have today.
I might be wrong; he was certainly not convinced. So it will be interesting to see what happens if or when the writers let their personalities loose in the doc set. Maybe we've got a bunch of David Pogues and John Muirs and chunky-bacon-loving foxes in our midst and we just don't know it.
[categories]
writing, editing, work
|
link
|