December 96 - The Veteran Neophyte: Confessions of a Veteran Technical Writer
The Veteran Neophyte:
Confessions of a Veteran Technical Writer
Tim Monroe
I've been a technical writer long enough to have learned a few trade secrets,
if you will, that guide me in my daily work and (sometimes, I hope) help me to
do it a little better. Whether you're reading manuals for content, working with
technical writers to document your own software, or even writing documentation
yourself, understanding these secrets might be of value to you. I've long had
it in mind to write a book about these and other topics, sort of a general
discourse on technical thought and how to do it better. Until I actually write
that book, however, the following confessions will have to do.
These confessions should help you understand some of the tasks that some
technical writers typically perform and some of the conflicting forces that
shape final documents. (Note the profusion of the word some: your mileage may
vary.) For fun -- and for another reason that I won't tell you yet -- each
confession is introduced by an appropriate palindrome (a word or phrase that
reads the same forward and backward).
As you probably know, Adam was given the task of naming the plants and animals.
In a way, Adam was the first technical writer, for an important part of
technical writing is to systematize and regularize the nomenclature used in
some specific area of interest. It's rare for the engineers developing software
to pay very close attention to naming issues. Indeed, the rule is quite the
contrary: more often than not, the technical specifications written by
engineers are rife with conflicting, inconsistent vocabulary. It nearly always
falls to the writers and their editors to clean things up and present the
technology using clear, regular, and concise terminology.
There's a moderately foolproof way to discern which writers take this job
seriously and which do not: just look at a document's glossary. For my money,
every draft of every technical document should include a robust glossary that
defines the special terms and concepts used in the document. You simply cannot
write any significant part of a technical document without grappling with
naming issues. A working, growing glossary is the writer's proof that he or she
is actively thinking about these issues and is developing a preferred
vocabulary to describe the technology being documented.
Don't be misled by the fact that the glossary is usually one of the last items
in a book: as I see it, the glossary ought to be written concurrently with the
book, not after it. (The index is another issue altogether: a book cannot be
properly indexed until it's nearing completion. Trying to do an index while a
document is still changing usually results in tremendous frustration.)
At some point in the distant past, Apple Computer reached an agreement with the
Beatle's record company, Apple Records, that allowed Apple Computer to use the
name "Apple" so long as it did not engage in certain markets, such as music
recording. At some later point in the distant past, Apple Records sued Apple
Computer, alleging certain violations of that agreement. Suddenly, the lawyers
at Apple Computer were intensely interested in the sound and music capabilities
of the Macintosh hardware and system software.
At that moment, I happened to be finishing up the Sound Manager chapter of
Inside Macintosh Volume VI. Apple's lawyers decided that a number of API
elements smacked too much of music and needed therefore to be changed. For
instance, it was thought that since music is composed of individual notes, the
word note should not occur anywhere in the documentation in any sound-related
sense. As a result, what was hitherto known as the noteCmd constant was changed
to freqDurationCmd (the idea being that playing a note is just playing a
frequency for a specific duration). The legal department demanded a number of
other changes, which led to some last-minute rewriting and reindexing as the
book neared publication. And, of course, the engineers had to issue new header
files to reflect the new names.
I don't imagine that Yoko Ono and other Apple Records executives have spent
much time reading Inside Macintosh, so I doubt that my efforts were all that
critical. Nonetheless, I learned my lesson. I confess: I've come to appreciate
the difficult job done by the Apple legal department. I now pay close attention
to the lists of trademarks distributed by the editors in our department, and
I'm constantly on the lookout for API elements that might step on someone's
copyrighted toes.
Let's face it: technical writing isn't creative writing. It's not designed to
enthrall, just to educate and to serve as a useful reference during your daily
work. To be useful, a technical document has to be complete. It also has to be
consistent in style and vocabulary with other similar documents -- in my case,
with other
Inside Macintosh books. ("No manual is an island.") Providing
documents that are both complete and consistent usually means following a
pretty strict set of rules and guidelines governing the style, organization,
and content of the document. It can get to be drudgery, sometimes. Yawn.
On the upside, having rules and other established methods to follow can be
incredibly liberating. These shackles free you from constantly having to
rethink major issues about a document you're writing. Once you figure out what
goes where, in a general sense, you almost don't need to think any more. You
just take the API elements that need documenting, plug them into the correct
paragraph formats, and fill in the appropriate information. It can get to be
too easy, sometimes. Yawn.
Following rules, though laudable, is not without its own problems. The
requirement that every constant in an API be precisely described can result in
some pretty silly stuff. For instance, page 2-33 in the book Inside Macintosh:
PowerPC System Software takes the trouble to inform us that the constant
kRegisterD0 stands for the register D0. Did anyone have any doubt about that?
It can get to be too dumb, sometimes. Yawn.
Have we reached the stage where the API is self-documenting, where just the
names of functions and constants give us all the information we need to use
them effectively? I don't think so. It's just plain dangerous to start having
writers decide what's too obvious to need description and what isn't. In my
mind, every element of an API should be fully documented, even if we end up
with a few odd cases where there really is nothing more to say. Remember,
degenerate cases like these are a direct result of systematically applying
rules and established methods. They're a clear signal that the writer is doing
things exactly right.
...I'd play it real loud, and I'd turn the bass way up. That's the only way to
play reggae music, which is what I listen to mostly. My taste in music is
quirky, but that's a problem of mine generally. I confess: I adopt methods that
help me get my work done, even if those methods are quirky. I revel in quirks,
because they often pay off.
So I'll confess another quirk of mine: I write my documents backward. For each
chapter, I start at the end and write the summary first. This actually makes
good sense, since what I'm documenting is usually an API, as defined by a
header file. The summary is really just an improved header file. It's improved
in part because it attempts to impart more order and consistency than you'll
find in a typical header file. It's important to keep in mind that header files
are designed for compilers, not for humans. There's lots of junk in these files
that has absolutely no meaning to a programmer. The summary provides an ordered
distillation of the header file to its key components.
Once I've written my summary, I have a good head start on the reference
section. That's because the summary already contains intelligent groupings and
orderings for the basic language elements. To write the reference section, I
simply need to "fill in the blanks" provided by the summary: Each constant
needs a precise definition. Each data structure needs to have its use
explained, and each of its fields must be fully described. Each function has
parameters that need describing, and it probably returns a value that must be
described.
Only when I've finished the summary and reference sections do I even think
about the first parts of the chapter, the About and Using sections. At that
point, I need to turn down the music and do some real thinking.
Good technical writing is far too often simply taken for granted. Partly that's
an occupational hazard: when it's done right, good documentation is
unobtrusive: it purposely doesn't try to be cheeky or clever. More important,
good technical writing is unobtrusive because it doesn't jar the reader with
confusing organization, sloppy diction, or bad transitions from one topic to
the next. Its job is to conform to established styles and norms, and to present
information as straightforwardly and clearly as possible. Nonetheless, it bugs
me that I've never seen a single review of any
Inside Macintosh book. Even
magazines that are geared specifically at Macintosh programmers, like
MacTech
Magazine, never actually bother to review these important books. Third-party
books get plenty of discussion, but not the primary documents they all draw on.
I see some other signs that technical writing is taken for granted -- like
product managers who try to bring a writer onto a project two weeks before the
CDs are to be pressed, and engineers who would rather have a root canal than
review the chapter describing the technology they've slaved over for months or
perhaps years. What these people are missing is that good documentation can add
a considerable amount of value to an engineering product. Documentation is the
first and most important bridge between the engineers and the developers using
their technology. If the documentation paints a compelling reason to adopt the
technology and facilitates that adoption by providing useful sample code and
complete descriptions of the API, the writer is a god. Occasionally, the "wow"
factor emerges: documentation that is so compelling that it opens your eyes
wider and makes your fingers itchy for some coding.
The flip side of the "wow" factor is the "dud" factor: documentation that is so
patently bad it almost single-handedly ensures limited adoption for the
technology it describes. I've seen some really good technologies languish for
years, for no other discernible reason than that they're tied to some really
lousy documentation. The best software technology and the best API cannot
survive a mauling by a dog technical writer.
Palindromes delight us because they call attention to a fairly rare phenomenon:
a sequence of letters that is meaningful and that reads the same forward or
backward. Language wasn't designed to be palindromic, and there is no cognitive
benefit -- no additional information -- in a particular phrase or sentence that
happens to be reversible. It's usually a serendipitous accident that some long
sentence should be palindromic.
At their best, palindromes tweak our sense of order. As I've suggested above,
order itself is deceptive. The linear order of presentation that you find in
technical documentation like Inside Macintosh reflects, in all likelihood,
neither the order in which the document was written nor the order in which
you're most likely to access the information in it. In fact, the principle
according to which most good documentation is organized is a complex hybrid of
at least two ordering schemes.
On one hand, there is a principle governing how you should be able to learn
from a document: you should be able to pick up a document (a book or a chapter)
and read it from start to finish with good comprehension. Concepts should be
explained in a clear, cumulative order, and tasks should be explained in the
order they need to be performed. I like to call this a pedagogically linear
path through the document. The good writer progressively reveals more and more
of the technology as he or she goes along. This is the main principle that
governs the opening sections of an Inside Macintosh chapter (the About and
Using sections).
On the other hand, there is a principle governing how you should be able to
find information in a document. Technical documentation is, above all, a type
of reference material. You're constantly jumping into the middle of a chapter
to find the meaning of a constant, or the type of a parameter to a function, or
some similar piece of information. It's common to call this random access to
the information, but I prefer to avoid that term, since it might suggest that
the information itself is ordered randomly. In my opinion, pure reference
material (such as that found in the reference and summary sections of Inside
Mac chapters) must be organized hierarchically, where the items are
intelligently divided into groups, which are themselves further subdivided into
groups, until every item can be reached by a meaningful path from the top of
the hierarchy. I like to call this the hierarchically linear path to the
information. (For reference material, the main competitor to a hierarchical
organization is the standard alphabetical organization, which some of you might
prefer. Personally, I like to have things grouped by functional similarity, not
ordered -- "one darn thing after another" -- by name.)
The pedagogical order and the hierarchical order are clearly different ways of
organizing information. If you follow a pedagogical path, you might not get
where you want to go very quickly, but you'll get a complete picture of the
terrain as you pass through it. If you follow a hierarchical path, you can get
where you want to go pretty quickly, but only if you already know where you're
going. So, to use the hierarchical path, you must already have traveled the
pedagogical path. These two ordering principles depend on each other and should
never be separated.
As you can see, order dominates my mind, at least when I'm writing technical
documentation. That's why my motto is a palindrome. Attention to order -- and
clearly understanding exactly what kind of order is relevant to the task at
hand -- is the foundation of all good technical writing.
- Go Hang a Salami! I'm a Lasagna Hog! and Other Palindromes by Jon Agee
(Farrar, Straus, and Giroux, 1991).
- Inside Macintosh by Apple Computer, Inc. (Addison-Wesley, 1992 and
following).
TIM MONROE (monroe@apple.com)
recently became a Senior Software Engineer in the
QuickTime VR group at Apple. He already misses the smart rams and star rats in
the technical writing group at Apple Developer Relations. In his spare time, he
likes to stack cats and drive his race car to the local llama mall.*
Thanks to Dave Bice, Sharon Everson, and Antonio Padial for reviewing this
column.*
