Re: Self Documenting Interfaces

[Per Lewau <perle lysator liu se>]

On Fri, 24 Jul 1998, Dan Kaminsky wrote:

> On Fri, 24 Jul 1998, Dan Kaminsky wrote:
> 
> >> I'm gonna take back my claim that voicing tours is preferable.  However,
> a
> >> text-annotated visual tour of a program and what it can do *IS* a good
> >> thing.  There's no better way to learn an app than to watch it in use,
> >> rewind, fast forward, etc.
> 
> >The best way to learn something is to do it. Provide instead of visual
> >playbacks guided tours of common operations. ("...and on the right we see
> >the famous Print button. By pressing that button we can produce hardcopies
> >of the document" :))
> 
> >A somewhat well-known principle is that you see and forget, you hear and
> >remember and you do and understand.
> 
> 
> A better known principal is documentation makes no sense.
> 
> I can come up with any number of people who believe this :-)

There is a difference between these two principles. The first has its
foundation in cognitive psychology and the other in shoddy documentation.
Just because most documentation is bad doesn't mean that the concept is.

> Anyway, for documentation purposes, what you see and do, you remember.  What

I would like to add some form of explanation to the seeing and doing. 

> you only hear and do, you totally screw up.  What you see and hear, you
> remember even better.  What you read and do, you hunt around trying to find
> the button the documentation says to push.

I never said that the tour should be made out as a written document from
which you follow certain steps. It should be a _guided_ tour, that is the
user should be guided actively through the exercise. The "guide" (which by
no means should act real, like the infamous paper clip) should take the
user through the requiered steps and explain them, one by one.

-----------------------------------------------------------------------
Per Lewau (perle@lysator.liu.se) Student of Computer Science at
				 Linköping University, 
				 Sweden. 
"Why waste time learning, when ignorance is instantaneous?"
						- Hobbes