March 93 - Editor's Note
In May of last year, I schmoozed with a lot of developers at Apple's Worldwide Developer's
Conference, and one of the subjects that came up was documentation. I expressed my ideas on this
subject somewhat hesitantly, because I thought the truths I was spouting were all pretty obvious, but
I was surprised to find that several developers seemed enlightened by them and even suggested this
as a topic for a develop editorial. So here goes.
But first, some motivation. If you're one of those developers who think no one reads manuals
anyway, has it occurred to you that this might be a self-fulfilling prophecy? If manuals were better,
maybe people would read them. Also, customers who do never read the manual will never learn the
full power of your product (probably not every feature is self-explanatory) and will be that much
quicker to move on when someone shows them the great things a rival product can do. More likely,
people glance at the manual to get started and then thumb through it later when they want to
explore certain features.
Also keep in mind that a shoddy manual will be seen as a reflection of the product as a whole: "If this
is the best they could do on the manual, how good can their software be?" Don't fool yourself that
only writers or editors will criticize a poorly done manual; any reader who has trouble learning from
it will complain, and not just to themselves. While there are times when consistency may be the
hobgoblin of small minds, it's often the case that inconsistent presentation or terminology will
confuse readers and have them throwing your manual down in disgust and thinking your product is
more complicated than it really is. And people who do know things like the difference between "its"
and "it's" will wonder how well you debugged your code if you couldn't find mistakes like this in
your manual. Basically, you won't look like a class act.
I'll state the following points with user documentation in mind, though most of them also apply to
technical documentation for developers. Some points may be useful only to small companies, but
there should be something here for everyone.
- Get a technical writer to write your documentation. Don't do it yourself -- and
try to talk the CEO or VP of Marketing out of doing it. Contrary to many
people's opinions, writing a manual is not something any smart person can do; it's
a skill like any other. Most likely you are no more qualified to write the
documentation than a writer is qualified to write your code.
- Look over a relevant writing sample from your prospective writer. Awards,
certificates, and years of experience go only so far: nothing will tell you whether
you'll get a good manual as much as looking at past work. Ask how the material
for the sample was gathered, who else contributed to it, and how heavily it was
- Get the writer started early in the process -- long before the feature set is frozen.
Writers provide a valuable perspective of your product, not unlike that of product
management. They'll help with the design of the product, telling you what
features don't fit in with other ones and pointing out loopholes, inconsistencies,
and other Bad Things. And they're typically excellent bug finders.
- Have the documentation edited by an editor. Unless they also happen to be
editors, writers need their work checked like anyone else -- and an electronic
spelling or grammar check (while a good start) isn't enough.
- Test the result on users, after your product ships if not sooner (you can revise the
documentation for the next printing). And don't be defensive: if only one out of
ten "testers" turns up a particular problem, it may mean that 10% of your user
base will have the same problem. Judge no misunderstanding as stupid; they're all
valid, no matter how much you may disagree with them.
I could go on forever, but that's enough for now. Please make my day and let me know if you got
anything of value out of this. Or criticize it if you like; I can use the practice in not being defensive.
CAROLINE ROSE (AppleLink CROSE) has been writing and editing software documentation since many of you were rug
rats. She began at a timesharing company, joined Apple in 1982 to write Inside Macintosh , and helped get NeXT off the
ground in 1986. Back at Apple now, she has seven issues of develop under her belt and is still having a wonderful time.
A transplanted New Yorker, Caroline visited the East Coast last October in time to see the leaves turn colors. She enjoyed
doing the theater and museum thing in Manhattan and hitting some incredible restaurants and nightclubs -- not to mention
a deli whose smoked mozarella is the best this side of Naples. But the highlight was her visit to a friend's farm in
Connecticut (sheep feeding beats sheet feeding any day!). Walking to an apple orchard and tasting fresh sweet cider was
sheer rural bliss.*
SUBSCRIPTION INFORMATION To subscribe to develop , use the subscription card in the back of this issue. Please address all subscription-related inquiries
to develop, Apple Computer, Inc., P.O. Box 531, Mt. Morris, IL 61054 (or AppleLink DEV.SUBS). *
BACK ISSUESFor information about back issues of develop and how to obtain them, see the last page of this issue. Back issues are also
on the Developer CD Series disc.*