Re: [Chicken-users] The Documentation Problem

[Matt Gushee]

Sven Hartrumpf wrote:

> Fri, 19 Jun 2009 02:25:28 -0600, matt wrote:
> > And I conceived of a project that might make it easier to access all the
> > various docs. I call it SUDS (Scheme Unified Documentation
> > Server). Basically, there would be a lightweight Web server (maybe
> > Spiffy-based?) that could be deployed either on the public internet or on
> > your own computer. It would have a database of all the reference docs for a
> > particular system ... so for Chicken, the DB would include R5RS, all
> > supported SRFIs, the Chicken manual, and docs for all the
> > eggs.
>
> There are several such projects with a solid infrastructure -
> but they sometimes lack user support.
> For example, please have a look at (and consider contributing to):
>
> SchemeCrossReference http://practical-scheme.net/wiliki/schemexref.cgi

Yes, I've seen this, and I think it's a worthy project, and I might well 
contribute to it, once I have enough expertise to do so. However, the 
focus is not quite the same. The central point I want to address is:

  * As an IMPLEMENTATION-X user, how can I gain a comprehensive view
    of IMPLEMENTATION-X?

More concretely, I would like to have a single point of access--and a 
single method of access--to *all* the key concepts and *all* the 
reference documentation for the *system I am using*. Surely there are 
many people who would benefit from such a thing. It may not be an 
absolute need, but IMHO it is much more than a convenience. In fact, I 
have a strong feeling that the difficulty of finding information is one 
of the major reasons Scheme has not been more widely adopted.

So what can be done? It is obviously impractical to maintain a single, 
comprehensive documentation package. But it might be feasible to create 
an aggregator that gives you the single point of access to all the docs 
you need, which is the idea of SUDS. I do think, as I stated in my 
original post, that it is crucial to be able to automatically populate 
the database. Otherwise it's very unlikely that the index would ever be 
complete and up-to-date.

With all that said, I would be delighted to find that something like 
this already exists. Sven, you mentioned "several such projects." Can 
you point me to some others?

--
Matt Gushee
: Bantam - lightweight file manager : matt.gushee.net/software/bantam/ :
: RASCL's A Simple Configuration Language :     matt.gushee.net/rascl/ :