Ongoing documentation discussion

[Rick Mascitti <acad!blitzen!rick>]

Wow!  Somebody has a few opinions on this subject.  Moving right
along, I'll be dribbling out my responses to the marcs quartet.

Part 1:

>  From xanadu!marcs Mon Mar  5 14:40:45 1990
>  From: xanadu!marcs (Marc Stiegler)
>  To: kmarvin@xxxxxxxx, xanadu!us
>  Subject: The Crucial Role Of Documentation
>  

And yet-another-plug for the InfoFactory (er, Tapestry). :-)

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

Fortunately, in my last position I managed documentation and test along
with product development.  It was great!  No messy organizational
disagreements about priorities for staff, proper staffing levels from
the start, etc.  There were actually times when the 'taters were prodding
the 'neers and 'grammers to design things so they could keep busy.
There's nothing like a professional writer going to a designer and
saying, "I'm trying to write this so it makes sense, but it doesn't!
Did you actually mean that the neck-bone is connected to the ankle-bone?"

Not to detract from the 'tation discussion, we should also open a similar
discussion on testing.

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

I would argue otherwise.  Good documentation of primitive tools will
have 3rd party developers realizing just how inadequate said tools are
much faster than poor documentation would. :-)  What is needed for
success is good documentation of *good* tools.  Either condition alone
is necessary but *not* sufficient.  (Merely a quibble over the value
of tools, not the necessity of high-quality documentation.)

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

Agreed.

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

I'm not as convinced about Tapestry being the right tool as you are.
See follow-up in appropriate sub-missive.

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

Indubitedly.

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

I choose to read all messages and offer my twopence worth.  This would
be easier with Tapestry already implemented.  (Note that Tapestry *is*
the *exactly* right tool for this discussion.)

rick