Re: Self Documenting Interfaces

[John R Sheets <dusk smsi-roman com>]

Tom Vogt wrote:

> Dan Kaminsky <effugas@best.com> wrote:
>
> > I think Screenplays make the ultimate illustrators.  I used to debate and I
> > KNOW how bad alot of people are at speaking; I wouldn't want to have to
> > DEPEND on speech for documentation.
> we would need ONE speaker - for consistance reasons.
>
> I don't think this whole thing is possible. if it were, it would be a nice
> thing, especially for newbies. guided tours WITH interaction (else you get
> bored!). but I don't think it's possible, so there we go.

I agree in the sense that it probably wouldn't be _practical_ to integrate all
this animated playback within GNOME apps.  Technically speaking, it is certainly
possible -- if you don't mind bloating things tremendously.  Not to mention tying
the software release schedule to the help system production schedule (assumedly a
significant time investment if you're going to do a good job).

A better solution is to soup up the help system (or create an animated extended
help system), and allow interested parties to write & produce high-quality
tutorials (with full-motion text/voice/whatever) at their own leisure.  But don't
tie it to the original app.  Make it a separate module that you can download -- if
you want to.  E.g. download panel as part of the regular distribution, and if you
can't figure it out, download the optional 4 MB panel tutorial.  It would be a
mistake to bundle all this high-volume, optional help material with the main
packages.

This would also free the original authors from the necessity of hacking a help
system in parallel with (i.e. linked to) the code.  It would be better to keep the
tutorials away from the applications' code.  This would solve the bloat problem
(including bug-bloat), and would allow the tutorial system to be as extravagant as
it needs to be.

John