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