[Date Prev][Date Next][Thread Prev][Thread Next][Author Index][Date Index][Thread Index]
Re: The Crucial Role Of Documentation
- To: <marcs>
- Subject: Re: The Crucial Role Of Documentation
- From: Bob Perez <bobp>
- Date: Fri, 9 Mar 90 12:15:00 PST
- Cc: <acad!kmarvin>, <us>
With all of the products I've seen over the last several years
as an evangelist and software champion, it's amazing to me how
difficult I find it to name any examples of outstanding user
documentation. But it's true: documentation is still a second
class citizen in the software community. This community hasn't
even progressed to the point of treating documentation as a "separate
but equal" partner; most developers are still in the Dred Scott
stage, treating it as property with some value, but little dignity
But documentation is just one prong of the larger problem of
making systems approachable. Effective user interface design
is another way to reach the same goal, and is the approach favored,
for example, in the Mac community, where the key evaluative question
remains "can you run it without a manual"?
Accessibility barriers are a nasty, hidden problem that touch
more than just particular products; whole software categories
are affected. I constantly hear that "telecommunications hasn't
yet arrived" because of the extraordinary difficulty people encounter
using telecommunication software -- this is incredible when you
consider how many people use telecommunication software everyday.
The perception is that it's largely inaccessible magic, available
only to those dogged (or idle) enough to brave the mountains
of techno-gibbereze that accompany most telecommunications software
Now consider the success of AppleLink, an Apple telecommunications
program thoroughly stupid and wretchedly awful. The address book
must have been designed by saboteurs from IBM. The program actually
interrupts you periodically and without warning and tries to
cut your connection; the intrusive disconnect dialog's *default*
behavior is to log you off unless you indicate by mouseclick
otherwise. So, if you happen to be typing a return key at the
time this dialog comes up, the Mac will dutifully translate that
action into an explicit acceptance of the dialog's threat, trashing
your connection and leaving you limp, with mute (or maybe not
so mute) anger.
Yet Applelink is used everyday by virtually Apple software developer,
employee, dealer, and user group. Why? Maybe because the software
is given away free; but that only explains why they have the
software, not why they use it. The real reason is that it's the
first telecommunications program on the Mac that's _really_ easy
to use. I've *never* known a person to ask for an AppleLink manual,
and the latest version of the software doesn't even have a manual
(an address is provided so that you can write away for one).
As impossibly stupid as the program is, with it, you spend virtually
no time on the "tele-", and all of your time on the "communications".
One of the most arcane corners of the software marketplace has
suddenly become accessible to tens of thousands, and without
a single page of documentation.
Having said that, you can imagine my reaction to your primary
>The key to success for our third party developer tools will
not be the >richness and power of the tools themselves, but rather
the quality of the >online ... documentation...".
I really admire your ability to sink deeply into the analysis
of a problem and then emerge with an explosion of ideas all synchronized
so well and leading to the same inexorable conclusions. You should
have been a lawyer! :-) But in this case I think you've been
submerged too long. Or, you're exagerating to make a point, I
can't tell which. But as much as I agree with you that online
documentation is useful and even very important, I disagree with
your particular assesment of its role as the "key to success".
Actually, we agree more than the above statement suggests. My
meta observation is that the key to our success lies in delivering
that degree of _access_ to Xanadu that you feel will best be
delivered with online documentation. I believe that effective
online documentation plays an important role in that delivery
process, but I also believe that the particular needs of our
customers also drive a very different set of objectives.
A software developer is a unique combination of artistan, craftsman,
and businessman. He will base his business decision to pursue
Xanadu on his calculation of the market potential for Xanadu,
and not on any of the romantic notions that have kept Xanadu
alive in its early years. Our challenge is to present him with
the strongest case for making that favorable business decision,
and then to provide him with an environment that lets him use
the craftsmanship and artistry that (hopefully) brought him into
the market in the first place.
I don't think we're going to sell him on the business decision
by providing him with good online documentation. As impressed
as he will be by a living example of the wonderful utility of
our products, the decision is likely to be made on the basis
of factors having little to do with how wonderful our stuff is.
Sad, but true. I've never known a successful developer to get
onto a project that he thought was a good idea but a losing business
>"How are we going to imbue the developer with a sense of wonder
when he's >faced with a hundred pages of subroutine calls and
By making it quick, easy, and fun to use those subroutine calls.
ThinkC and ResEdit are great examples of graphic, interactive
tools that make programming a complex system absolutely *fun*,
despite the fact that ThinkC's documentation is sparse and weak,
and ResEdit's virtually non-existent.
When programming the Mac, I don't think much about the hundreds
of pages of Inside Macintosh that I have to wade through; I just
keep them around as a necessary reference. The quality of my
life would be much improved if I had a good online documentation
system on hand, but the availability of such a system won't be
a determining factor for me. My principal frame of reference
when I think of the experience is the nature of the tools that
I use during that process, and the sheer pleasure I derive from
watching things built up from the use of those tools. For me,
MPW and Rez are no fun; ThinkC and ResEdit are loads 'o' fun.
The tools I'm designing are actually inspired by the ResEdit
model. Rather than having to specify a written list of rect coordinates
(the Rez way), I want to drag a rect across the screen (the ResEdit
way). Rather than having to specify a written list of menu items
(the Rez way), I want to put up a mock menu and and futz around
with it on the screen until I've got it looking the way I want
it (the ResEdit way). Rather than having to write long, complicated
make scripts (the MPW way), I want the computer to figure out
what depends on what (the ThinkC way). And rather than having
to specify a written list of EndSets, I want to put a bunch of
objects up on the screen and literally see what they look like
and how they relate to each other graphically.
The many, many programmers I know who use ThinkC and ResEdit
enjoy their time writing applications. It's interesting to note
that while MPW is Apple's officially sanctioned development environment
,it only commands 40% of the development environment market,
with most of the remaining 60% going to Symantec for ThinkC.
And we're talking about production code, here -- the list of
applications created with ThinkC is telling: Aldus Pagemaker,
Digital Darkroom, Adobe Illustrator, Adobe Type Manager, Quark
XPress, Aldus Freehand, FoxBase Mac, SuperCard, MacWrite II (!),
and on and on.
The point is that if you make the tools themselves easy and fun
to use, and sell developers on the business proposition, they
will approach their task with an enthusiasm that cannot be duplicated
by having an impressive suite of online documentation, poor tools,
and uncertainty regarding the business prospects.
I agree completely with your emphasis on our developer toolkit
as critical to our future success. But I think our concentration
should be on providing the best tools themselves (i.e., the most
fun, the easiest to use, the most powerful), and then supplementing
these with excellent online documentation. The combination of
the two, of course, is the show-stopping objective.