Re: Documentation

[John R Ellis <Ellis@YALE.ARPA>]

    I would extend that and say that many problems people have stem from
    the lack of available (ON-LINE) documentation.

And not just with T, but all our new systems.  Unfortunately, most
implementors have neither the time nor the patience nor the supporting
framework to maintain documentation.

Given that we have only one full time T implementor, however, it is
unreasonable to expect him to do much in the way of providing more than
the basics.  I'd rather Jonathan devoted his energy to getting out new
releases and working on the new compiler, wouldn't you?

Improving the availability and organization of on-line documentation is
a task that lots of other people around here are fully capable of.  As
a group graduate students have to stop whining and sacrifice some of their
own time if they expect improved environments; the facility doesn't have
the resources to do anything new, and the department is politically
incapable of hiring more talented people at competitive salaries.

To start with, why doesn't someone implement a index-based help system
for the Unix and Apollo like the one on the -20?  I think Jonathan has
already indexed the T manual to some degree, so that automatically
generating a rudimentary program-readable index from the Scribe sources
shouldn't be too hard.  If the system were written in portable C, it could
be easily be made directly accessible from T.

Or even simpler, someone could implement an on-line HELP function for
just T similar to the one in R/UCI Lisp and in Rutgers ELISP.  There are
incredibly simple-minded but very handy, obviating the need for most T
programmers to keep a manual by their side.

Once someone has established a robust framework, even a simple one, then
it is much easier for implementors to keep documentation up to date.
-------