[Openmcl-devel] Interest in documentation reorganizationl?

[Dan Knapp]

Hi there!  I'm coming to OpenMCL/Darwin after using CMUCL/Linux for a 
year or two, and so far I've been really happy with what I've seen.  
The FFI is well-designed, and the Cocoa binding, though a work in 
progress, is the right approach.  I'm sure you all knew that, but hey.

While I don't expect to have time to assist with any large changes to 
the system, I'm happy to volunteer for any small things that people 
might need done.  There's one thing in particular which I think the 
project is sorely in need of - reorganized documentation.

As things stand, FFI functions are described in three or four different 
html files; while it's clear why they were organized that way, it is 
not easy for a user to find out what facilities exist, or what they are 
called.  The minor utility functions could just as well go in any of 
those files; none really fits better than the others.

The rest of it is not that bad; but there's no clear overview of what 
documentation exists, nor any recommended reading order.  I eventually 
had to resort to looking at the filenames to find a couple things.

I envision a document structure similar to the CLHS.  The introduction 
of concepts would be separated from the detailed descriptions of 
function semantics.  Everything would be heavily hyperlinked to nearby 
nodes.  There would be a symbol index and a table of contents.

What do other people think?  If it sounds like a good idea, I'll try to 
put something together over the next week or so.

-- Dan Knapp