The Crucial Role Of Documentation

[Marc Stiegler <marcs>]

All through my life in software development, I and the people 
I've worked with have talked about how important documentation 
is. But in fact, in every project I've seen (including the ones 
I've worked on), documentation has always gotten the least resources 
last.

I have been as guilty of this as any of the people with whom 
I've worked whom I would prefer to blame :-)

Anyway, I have been thinking about this a great deal for the 
past couple of weeks with respect to Xanadu's products. My value 
system has undergone a phase change. I have reached the following 
conclusions:

1) 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 (i.e., hypermedia) documentation of 
those tools. Effective tools for our third parties can be simple, 
maybe even primitive; the online documentation cannot.

2) The Hypercard Tutorial/Help system was a quiet but brilliant 
pinnacle in the history of online documentation. Even though 
it has been around for 3 years now, surprisingly few people have 
grasped how good it was or how much better it is than many other 
newer online help systems. We should, we can, and we must, reach 
out from that pinnacle, not from the popular neighboring valleys, 
if we wish to ensure that people grasp and use the wonderfulness 
of our creations.

3) Even with the Tapestry frontend, we can build excellent online 
documentation. There are a number of specific techniques we can 
use in Tapestry to embody many of the key benefits of the Hypercard 
Help system despite the relative sparseness of Tapestry's features.

4) We need to focus on the quality of the online documentation 
with the same sincerity that we have focused on the quality of 
the server.

If you already accept all the above statements, you may wish 
to skip over my next 3 messages. If you don't believe 1) above, 
then please read the next message, which is the discussion of 
why and how hypermedia documentation transforms the utility of 
a product. 

If you expect to get involved in writing hypermedia documentation, 
you may be interested in the second message, which starts with 
an analysis of why Hypercard's Help is so good, and outlines 
some style concepts for good online documentation in general.

If you expect to use Xanadu frontends to write hypermedia documentation, 
then by all means read the third message, which discusses implementations 
of those concepts with the Tapestry frontend.

--marcs