Documentation response part 2

[Rick Mascitti <acad!blitzen!rick>]

>  From xanadu!marcs Mon Mar  5 14:40:53 1990
>  From: xanadu!marcs (Marc Stiegler)
>  To: kmarvin@xxxxxxxx, xanadu!us
>  Subject: Computer Programs and the Sense of Wonder
>  
>  
>  
>  This message has three major sections: 
>  
>     First comes a discussion of the real reasons for the allure 
>  of Hypercard, during which I propose that the documentation plays 
>  a role as critical as any other feature of Hypercard. 
>     Second is a discussion of the impact of even inferior online 
>  documentation on product utility. 
>     Third is a discussion of documentation's importance to our 
>  upcoming products, ending with a proposal that our software developer's 
>  toolkit is the most critical target for online help.
>  
>  What is it that makes Hypercard and Hypertalk so alluring? What 
>  makes it so "easy", so straightforward to go in and do something 
>  and be thrilled by how wonderful your own efforts have been?
>  
>  Most people would point to the english-like structure, the interactivity, 
>  the fast turnaround, and the nifty graphics that Hypercard makes 
>  possible. And that is about 50% right. 
>  

No.  It was the fact that it was Apple marketing "programming for the
rest of us" and giving it away.  The real question is, Why did the
strategy work for Apple and not for IBM&clones (Basic on the PC)?"
I will argue slick packaging (programming as playing), the non-conformist
Apple image, excellent documentation with immediately-available third
party "How-To" books, voodoo cult worship, and technical innovation.
In that order.

>  But the other 50% is the DOCUMENTATION. It's not just Hypercard 
>  itself that is interactive: the documentation is interactive 
>  too. When you encounter a problem, or can't remember how to do 
>  something, or don't know if you can do something, you are almost 
>  always within 4 mouseclicks of the answer.
>  

Four is two too many.  (See, I'm already offering suggestions for
improvements.)

>  The hypertextual representation of the Hypercard's documentation 
>  is crucial to its feeling of wonder. If you doubt this assertion, 
>  you do not have far to look to find a striking contrast: try 
>  using Supercard. 
>  
>  Supercard is a straight superset of Hypercard. It is more powerful, 
>  more flexible, just as english-like, just as fast in the turnaround, 
>  and the graphics are niftier.

But not *free* inside the cereal box.

>                                  There's a certain clunkiness to 
>  the user interface due to the 3 "modes" of operation in Supercard. 

Yup.  Already enough on the minus side of the ledger to warrant "less
wondrous" status.

>  But that only partly explains why Supercard has only a fraction 
>  of the sense of wonder that Hypercard has. The other clunky problem 
>  with Supercard is even more fundamental: before starting Supercard, 
>  you carefully lay the paper manual next to your keyboard. When 
>  you turn Supercard on, you brace yourself for long periods of 
>  thumbling around. No mouseclick magic here!
>  
>  Going to a paper-based manual is so painful

not to mention downright stupid for a hypermedia product (note that
stupid is much > silly)

>                                              that I usually just 
>  use Hypercard, trading away the product's power for the speedy 
>  documentation. When I do use Supercard, I keep Hypercard turned 
>  on at the same time--so that I can use the Hypercard Help system 
>  for the subset of Supercard features that Hypercard Help covers.
>  

I don't use either.  Of course the Mac is not my mainstay computing
environment.  Nevermind.

>  Even poor hypertextual help systems make a world of difference. 
>  I have hated Microsoft Word ever since Release 1. I have never 
>  learned to use it, for anything. Well, Word 4.0 has somewhat 
>  effective online help. In doing my recent research about online 
>  documentation, I spent an hour with Word 4.0 to find out how 
>  much of a difference it made. 
>  

You braver than I, kemosabe.  My 'taters had to use this wretched
vessel of excrement (3.0, I believe) and it was mightily pungent.

>  The difference was striking: by the end of the hour, I was able 
>  to do things in Word that I've never been able to do on a computer 
>  before.

I definitely *don't* believe this, Marc.  Maybe a tiny little exaggeration
here?

>          I still don't like Word, but I can use it, and do amazing 
>  things with it. And learning how to do them was pleasant despite 
>  my horror at many of Word's characteristics.
>  

Try RSG or some other writer's tools.  Professionals' tools should be
intuitive enough not to require so many dead trees.

>  Small differences are important, however: Word 3.0 also had online 
>  help, I'm told--but I never found it. I'm told it was hidden 
>  in the About box, and the rest of the program was deactivated 
>  while the help was running. This made it quite irrelevant, at 
>  least for me.
>  
>  Anyway, lively documentation can make the difference even for 
>  products that are otherwise awful, like Word. It lifts good products 
>  into a special class of wonderfulness, like Hypercard.
>  

Maybe ``lively documentation'' can turn Sumerian clay tablets into
papyrus.  Or not.  I'd rather just agree with the last sentence than
continue this tedious and tenuous vein about its value for products
like Word.

>  This has something interesting say about all the Xanadu-related 
>  products we're doing: Montage, Tapestry, and the programmer's 
>  toolkit. The product that's most immediately important--and the 
>  one for which I believe the big payoff is biggest, is the programmer's 
>  toolkit. Montage's language is planned to be easy to learn; Tapestry 
>  is point-and-click in every nuance; but the tools for C and C++ 
>  programmers are going to be, at best, strange and alien. 
>  

Too bad you missed my presentation at XOC.  The Scheme Objects in Montage
are direct mappings of the C++ objects are directly wrapped in the C
library.  These ``strange and alien'' tools are going to implement
Browsers and Editors in Montage, are going to implement Tapestry (whether
it's done via Montage, C/C++, or Smalltalk) and these implementations
will be available for scrutiny by developers.  Moreover, I hold that
(at least for Montage) the "Browser as Librarian" is a key concept --
the implementation will be linked with the documentation, similar usages,
test routines, etc. at a fine-grained level.  The implementation of
Montage will (and I hold that the implementation of Tapestry should) *be*
its documentation and that of the tools used.

>  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? How can we thrill the ordinary programmer 
>  with the thought of working with ideas so alien that even we 
>  ourselves have trouble with them from time to time? The only 
>  possible answer the first time we enter the marketplace is to 
>  supply wondrous online documentation. The only possible answer 
>  with our later, even more powerful (and thus more complex) 
>  tools will be even more wondrous online documentation. Learning 
>  Xanadu will always need to be joyful; sitting down to program 
>  it after a month away needs to be alluring, not frightening.
>  
>  The next message in this series discusses some concepts behind 
>  wonderful online documentation.
>  
>  --marcs

Maybe I'm jumping ahead, but here goes.  These wonderfully strange
and alien tools are going to be delivered as a XanaBase, no?  Intertwingled
with the tools are examples, tests, manpages, overview documentation,
and further reading, no?  As a non-Montage example, me, Joe Random
Thirdparty C Hacker, starts to implement my SaveTheWorld application for
Xanadu.  I need to use FooLinks, so I grab the foolink.h passage from
the docuverse, complete with its multiway links to everything those
clever Xanadudes could imagine might be useful to me.  Tapestry would
be OK here.  The Montage Browser would be OK here (it will be even better
for Montage hackers).  Any Xanadu browser would work.  Get the picture?

not barking up the wrong hydrant,
rick