EDITOR'S NOTE

CAROLINE ROSE

 Dear Readers,

 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 edited.
• 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 Editor

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.*