No first grader ever said, “When I grow up, I’m going to be a technical writer.” You might as well say, "...a motel maid." A job which I have also done [1].
And yet: the technical writers were the guardians of peace and justice in the old Republic [2]. Technical writing, like science fiction fandom, flowered amongst a particular generation, at a particular time, for particular reasons. And now many of us who flowered with it are no longer in the role, and all of us are growing older [3]. But walk us past a situation with information missing or badly presented and our fingers tremble uncontrollably, as we fight the urge to pull on the battered armor and lift the heavy jousting pen, one last time…
Aside from the occasional jerks that every profession has [4], I have liked and admired all the other tech writers I met. The brother/sisterhood of tech writers was a cross between a secret society and an effective union. Our informal authority (such as it was) flowed from our knowledge of what was going on and our willingness to tell the truth; to any other who offered the secret handshake, we would tell it. Even if she had just wandered in on a job interview. Especially then!
I began my career in start-ups and had never been edited ("edited? what’s that?") until I worked for Kate Kush and Pam Friedman at Index Technology. Manuals that came out under their direction were like poetry: every word carefully chosen, pulling its weight. Because they described a complex product (Excelerator, for systems analysts and designers), some purchasers even read the manuals [5], and their graphic design was crisp and strong [6]. Maybe you once had a job like that, too, where for a while everything came together, so that despite each of our individual flaws, we could all do good work. Maybe you still have such a job: I am very happy to hear that!
There were also the gritty jobs, where bringing order out of chaos felt like a martial art. Once, documenting the work of twelve programmers, I observed six of them using credits and debits one way, and the other six using them the opposite way: Team A’s credits were pouring into Team B’s debit registers, etc. Fortunately it was three months before ship and the manager quietly sorted it out and the story has never been told (until now). After deployment the twelve (guys) were each given leather portfolios with their names on them in gold, and when I received one too my colleagues said with puzzled eyes, "How nice of them." I still treasure it: a medal for non conspicuous gallantry, the essence of tech writing.
That particular company was also where I learned how to explain tech writing to the managers who employed me. Rather than hiding behind the rather frightening stereotype of the "writer" (has scary hair? drinks? other signs of torment ad lib.), I tried to explain what writing had in common with bricklaying: in the morning the stack of bricks is here, and by quitting time the bricks are over there. Whenever they asked me for a schedule I made a great show of consulting the meticulous records I kept in a desk-sized Day-Timer. "The last time you asked me for one of those it took two weeks from the date when all the information was stable. So if you tell me when your product’s interface will be frozen, I can finish the manual two weeks after that." ("More graceful preferably." – Wolcott Gibbs.)
There is still a need for specifications and documentation; it’s just that there are fewer full time jobs writing and editing them, now that so much software runs on phones and tablets and in web browsers, now that the best interfaces attempt to be their own documentation. (Many tech writers went into usability and UI design for this very reason.) And as I have said in the footnotes, I am thrilled by the continued refinement of online knowledge bases, especially those where each reader gets to vote on whether an article was helpful. The projects we worked on would seem like "constructing a mnemonic memory circuit with stone knives and bearskins" [7] to you kids...
I only mention all this because I am about to review a novel by John Sundman. Back in the day he was a legend among technical writers. And his Cheap Complex Devices contains some jokes that (it seems to me) only another technical writer of a certain vintage would "get". So it behooves me to record my impressions of this novel before all of us perish from the earth. I can already see that my review will be more about me than about John’s novel, but it has ever been thus, or as Oscar Wilde once wrote, "The highest as the lowest form of criticism is a mode of autobiography." We will now conclude this arrest with an 'ymn [8].
Footnotes:
[1] The old-style technical writers cleaned up after people, too, so the jobs have significant commonalities. Being a motel maid in a tourist town was not much like working for "Housekeeping (dial 2)" in an actual hotel. We dressed down and the guests never saw us. I’m glad that Maid in Manhattan, as unrealistic as it might have been otherwise, gave housekeepers some love.
[2] You have a mythology about your job, murmured Margery Meadow, the day I first said this. Among her many felicities as a friend is keeping me honest.
[3] (What’s up with that? I thought it was only programmers that burned out!)
[4] An argument could be made that I was one of these. Just trying to keep with the honesty.
[5] My sisters and brothers in the guild will rightly ask for data here. Our surveys at user group meetings indicated that 10% of users (1 in every 10) used the manuals. Moreover, when people did crack the manuals, we got one chance: if the index didn’t have the exact synonym they were looking for (mapping multiple user terms to what the product called it) or the TOC wasn’t sufficiently skimmable, they’d tell their colleagues not to bother, ever. Do these numbers seem bleak to you? Then, sirrah, you lack the mental toughness that technical writing requires. Users only read when their backs are against the wall; they strongly prefer to ask another person for help, so if there is "tech support" they’ll go for that. Some work groups would have a "local expert" who read the manuals for an entire group, thus getting the needed info out there indirectly…
This was back in what could be called the golden age (at least for sets of printed documentation); since then we’ve had the end of shrink-wrapped software, documentation budgets slashed, but also the rise of third party documentation (…for Dummies, Missing Manual, etc.) and interactive web help where users get to rate each article for helpfulness and contribute their own tips. So the locus and methods of writing have moved but it’s still technical.
[6] The designers, who worked upstairs, were both gifted and humble, and they had state-of-the-art tools. And the development staff had an unusually high percentage of women. An unintended consequence of this was that too many development shops in the area had almost no women, but for awhile, it was an amazing team. I’ll have to write more about it.
[7] "The City on the Edge of Forever", Star Trek: The Original Series episode #28, story and script by Harlan Ellison and others.
[8] "Dead Bishop Sketch", Monty Python. Almost no one notices this ending line because they’re still considering the list of "afters": rat cake, rat sorbet, rat pudding, and strawberry tart. Those of you of a certain age may now recite the rest. You know you want to.
Enjoyed reading that post. Well written. Great voice.
www.DanielDickey.com
Posted by: Daniel Dickey | 08 March 2011 at 09:23