On Sat Nov 04, 2006 at 03:49:33PM +0100, Marco Baringer wrote:

personally i believe the things like doxygen, while usefull, should only complement a hand written user manual. using something like sbcl's docstrings.lisp would be cool for the swank configuration variables, but i'd strongly suggest keeping the current model.

I agree, the manual should be largely hand-written. But one of the reasons documentation always falls way behind rapidly moving development projects is that its out of date as fast as you write it. What I'm envisioning is a way to automatically generate the outline - with all the stubs - which keeps all the hand-written content as it is added. Everytime this document 'generator' is run, it adds any new stubs and maybe flags ones that no longer exist. An additional very power feature could be automated linkage of functions/parameters,key-bindings, etc to their definitions. Using the current model would require this all be done by hand, which means it will almost never be done, or done completely. I was thinking of writing something in Lisp to generate and update the documentation. Does this sound like a bad idea? -Jeff

Dan Weinreb <dlw@itasoftware.com> writes:

That said, I do think that the documentation should be kept in the same version control regime as the code. Developers with commit privileges must get used to the idea that whenever making a change with user-visible consequences, this document should be updated. My 2 cents.

Currently we only have 1 cent for your two: the texinfo source for the manual is in the same CVS as the code, but we have been pretty lax on updating it. Cheers, -- Nikodemus Schemer: "Buddha is small, clean, and serious." Lispnik: "Buddha is big, has hairy armpits, and laughs."