[Chicken-users] YADT: yet another documentation thread

[Vincent Manis]

I was offline for almost all of the documentation discussion, so  
please pardon
my beating a somewhat dead horse. I'd like to make the following  
points, which
(mostly) haven't been raised.

1. Total agreement that the first item of business is to fix the small  
stuff,
and that no Grand Vision (TM) should interfere with that.

2. The critical thing for the future is how we can reach new potential  
Chicken
users, as Chicken becomes more and more of a serious competitor to  
languages
named after snakes and shiny stones. I believe that the current  
documentation,
while fairly good, can be reorganized to make it more accessible to  
Scheme
newbies, who probably have no clue where to get started.

2a. At present, a Chicken user has to be aware of
 - R5RS
 - the relevant SRFIs
 - the Chicken core
 - the appropriate eggs
as well as other stuff outside Chicken (e.g., SQLite, Tk, Apache, etc.).
While the organization of facilities makes sense to us, a newbie has a  
real
problem sorting out that _member_ is described in R5RS, _any_ in SRFI  
1, and
_alist-update!_ in the Chicken manual.

I am definitely not suggesting a humungous manual that duplicates R5RS,
the SRFIs, and the Winnipeg phone book, but a good index and cross- 
reference
can really help.

2b. The basic principle of software documentation is to mirror the  
user's
questions and tasks, and thus I would like to see a new introductory  
chapter
that explains
 * what Chicken is
 * a discussion of what you need to have on your machine for
   - a minimal Chicken core
   - a pretty much full R5RS system (including the scary installation  
of
     GNU MP if you want numbers)
 * an introduction to using the interpreter
 * a similar introduction to using the compiler
 * an introduction to using eggs
 * a brief discussion of editors and IDEs
 * suggestions of resources for debugging, profiling, and preparing  
documentation
 * references and useful websites (e.g., schemers.com)

Much of this information already exists in the manual, but creating  
one chapter
that gets people started could really make Chicken vastly more  
accessible. (I'm
not proposing `Chicken for Brain-Dead Dummies in 24 Hours', just an  
introduction
for intelligent programmers who are new to Scheme and to Chicken.)

2c. There is a set of core eggs that one needs in order to make an  
R5RS system.
These would include numbers, perhaps a few more of the SRFIs. One  
might go a
bit further and add tinyclos. A brief discussion of these eggs, and  
including
their contents in the index, would help people find things more  
easily. I am
NOT suggesting that the system packaging be changed in any way, just  
that it
would make Chicken more appealing if people understand what they can  
have when
they install it.

2d. Don't underestimate visual appeal. A nice-looking printed manual,  
and
nice-looking online help will assist in spreading the message that  
Chicken
is in fact ready for prime time.

3. Eggs and egg documentation.

3a. The `wild west' phenomenon is what has made for so many eggs in  
the repository.
We should do nothing to our processes that in any way damages this.  
Heavyweight
processes, and elaborate documentation standards, will turn off the  
tap FAST.

3b. I take no position on whether documentation should be inline (a la  
Javadoc or
Doxygen) or separate. Both techniques should be supported.

3c. Users should be able to create addenda for egg documentation, with  
perhaps
tutorials, platform-specific information, or anything else that might  
be useful.
The standard egg build process should retrieve these addenda and  
provide them
as a standard part of the egg. (Again, having to search the wiki or do  
a Google
search acts as a barrier.)

3d. A checklist or guide should be available so that egg developers  
have some
ideas of what we think are good practices, including documentation,  
testing,
etc. This doesn't violate the `wild west' point above, because it's  
advisory,
not mandatory. (It occurs to me that a separate Egg Developer Manual  
might
not be a bad idea; this could include the current wiki tutorial, the  
guide,
and a discussion of how the Eggs Unlimited repository is managed.)

4. Technology and process.

What we have right now works adequately. I'd recommend we identify  
what we are
trying to accomplish, and then define suitable technologies and build  
processes
from that. I hope that, as much as possible, we make it easy for users  
to correct,
modify, and extend the documentation. Wiki-like systems are close to  
ideal for
that.

I apologize for being so verbose (in the words of Doctor Samuel  
Johnson, `I did
not have time to write you a short letter, so I wrote you a long one  
instead'),
but I hope the points raised here cause some thought. I know that this  
proposal
involves a fair bit of work; although I haven't yet made any  
contributions to
Chicken (not even one egg, though some might appear from me in the  
near future),
this is something I would be eager to participate in.

-- vincent