Re: The Crucial Role Of Documentation

[Bob Perez <bobp>]

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 
or significance.

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

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 
conclusion:

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

>"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 
interface specifications"?

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.

-- bobp