Re: Self Documenting Interfaces

["Dan Kaminsky" <effugas best com>]

-----Original Message-----
From: Joachim Schlesener <jos@tp.heise.de>
To: Dan Kaminsky <effugas@best.com>
Cc: gnome-gui-list@gnome.org <gnome-gui-list@gnome.org>
Date: Thursday, July 23, 1998 9:24 AM
Subject: Self Documenting Interfaces


>Dan Kaminsky writes:
> > ...
> >
> > [SUBNOTE:  Wow, I just realized a spiffy thing for GnomeTerm might be to
be
> > able to highlight a word and immediately send it to apropos, man,
HOW-TO, or
> > a specific search engine.]
> >
>
>Great idea. I think the help browser should be aware of highlighted text.
>And it should search through all availible documentation resources
>(man, info, html, faqs, pdf, ...) by itself and present a list of all found
>places with short description a la whatis. Could possibly be realized
>with a WWW search engine (?)


I'm probably one of the few people who will admit to liking some of
Microsoft's innovative UI components.  (Or admitting they have some...like I
say tho, can't outclass something you can't recognize the class of)

Anyway one of their coolest little toys is Send To.  Only works on files,
but it's an extremely easy to program interface that lets you send your file
through a given processor...straight from a second level heirarchy right
click menu.  Works better than it sounds :-), but when you get down to it it
should exist for EVERYTHING in GNOME.  Take a swath of text, Send To
Docs->apropos, man, info, etc.

> > ...
>
> > While tooltips shouldn't disappear, I'd like a helpme checkbox up next
to
> > the rest of the buttons.  This button would signal all tooltipappear ins
to
> > their normal boxes, blue and underlined.  They should be links to the
> > help/man/whatever file that describes their usage.  Click once, and the
> > tooltip unfolds in front of you with an indepth description of the
function.
> > This would of course posess a pushpin so if you wanted to have the docs
> > available while attempting to utilize a function, they'd be there for
you.
> > That's A Good Thing!
> >
>
>Sounds good. But I would prefer, if the indepth description would show
>up in the help-browser window because then I can read further, follow
>some hyperlinks, if I need more explanation, etc. My idea is, that it
>should be possible to click on the tooltip or press the Help-Key while
>a tooltip is showing, and then the appropiate help-page will be
>presented in the help-browser. By placing the application and
>help-browser windows side by side one could learn very fast - you
>navigate in the application window and at the same time you get the
>help texts in the other.


Maybe then Tooltips should "expand" into full fledged help windows, but in
the same place and obviously pinnable.

Remember, when you get down to it, watching a demo of a given action
occuring is *probably* more effective...we just need a simple way of
describing what key is being used.

I'm of the belief that all present systems, be they manuals, tooltips, and
online help, suck for one reason or another.  People probably learn best by
imitation.  We should take advantage of that.

>
> > There's more.  Us "experts" know that keyboard operations are orders of
> > magnitude more efficient than using a mouse.  The Xerox PARC designers
knew
> > this too.  So lets shift up a gear documenting what keypresses do what.
Why
> > not have a text entry box on the title that continually lists the key
> > combination that would have executed the last command.  For example,
click
> > the bold button in LyX, and a Control-B command is listed.  What if
there
> > *is* no command for a specified action?  There'd be a blank box, and the
> > user could move his or her mouse up to that blank box, click once, and
enter
> > their desired key combo.  It would show up in a different color, so if a
> > desired command was overridden by user preferences, its showup color
would
> > make clear what happened.  (Of course, there's need to be a dead-obvious
way
> > to list, add, or subtract commands.)
> >
>
>This is a really great idea. But after having learned the Shortkeys
>this text entry box would waste space and therefore it must be
>possible to hide it.


Sure it should be possible to hide it, but honestly, the idea is to have it
open so often that it's simple positive reinforcment, just like the bumps on
the road reassure you that you're changing lanes.

I wonder if the Shortbox should describe the actions of a given key combo?
And where should the Shortbox reside...in the title bar?  In the toolbar?
In the *shudder* status bar?  How bout a floating topped window(eek)?
Perhaps as a docked component in the toolbar of a given application?  This
is a user-config issue.

Of course this should be disablable.

By the way, the style guide MUST deliniate app keyspace from system
keyspace.  This is important, I don't need to go into why.

>Well, you asked for some comments.


I appreciate them :-)