What Are Software Documentation Specialists, Anyway?
by Karen Wise Olander
Home / Archives / Back Issues 1991 /
They call us "documentation specialists" in the biz. Our mail is addressed to "doc spec" because "documentation specialist" doesn't fit on mailing labels. At social gatherings, people's faces go blank when we say we write software documentation or computer manuals. But what are we, really?
When we prepare to write a manual for a new program, we become explorers. If technical specs are unavailable, we are Lewis and Clark, without a map. We learn the tricks to navigating through the software, and we get better at it as we go. Sometimes (too often) we discover new prompts or screens by accident.
When we get stuck, we go to the source. The trick is to meet the programmers on their terms and times (which always seem to be at odd hours of the day - or night). Now our diplomacy skills take over.
We work with a variety of people, many of whom have strong egos. Programmers, like engineers and scientists and lawyers and doctors -- and doc specialists, love their specialized language and like to use it when writing prompts, help messages and program overviews. We writers have to summon all our diplomatic skills when suggesting wording changes. We know programs aren't cast in stone, even if programmers think they are.
We're Ego-less Wonders
Writers have to have almost no ego. We wouldn't dream of issuing a document without at least one editor's review. And frequently our documentation has to go through many rounds of edits. Each reader will output better, so we have to be open to suggestions.
Perhaps the toughest challenge is to change a passage, then when it's reviewed again, change it back to what it was in the first place. We learn to smile, smile, smile. To be gracious, to argue only if it's truly wrong grammatically or doesn't fit with company standards. We don't niggle. We pick our battles.
When one user complains that a manual is too complicated, and another wants more in-depth information, we solve the problem by writing multiple documents designed to meet various need levels: quick reference cards, cross reference documents, tutorials, and multi-level manuals.
In companies where writing is low priority and the department short-staffed, we write, edit, word process, lay out pages, print, cut and paste, copy, assemble. And just about the time we complete all these steps for one manual, there's another one lurking in our in-basket, ready for updating. It is a sort of job security.
Desktop publishing is great, but it makes our work challenging, especially if we do not have design training. And then, when the word gets out that we can do nifty things with that laser printer and desktop software, we arrive at our desks in the morning and find a line of people waiting. Could you just print out this letter, this brochure, make a FAX form, do up a logo...
But most of all, we're true believers. We "doc specs" believe in writing -- good, clear writing. And we crusade to make our writing -- and that of others -- better and more accessible.