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 ofInside
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 linearpath 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.
RELATED READING
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.*