[Chicken-users] Egg Docs: Modifiability, Control, Both?

[Robin Lee Powell]

So there's a bit of a conflict between the wiki documenting Eggs,
and not.

On the wiki side, I really like the ability to add to documentation
because I tend to miss things that other people seem to find
obvious, and I like to be able to add to the docs in case other
peolpe like me (or myself, after I've forgotten) come along.

On the not-wiki side, some things are a bit silly to allow
non-developers to change (function definitions) but more
importantly, from my POV, things like that should really be in the
code as comments, and should be updated along with the code.  I use
mole to extract this stuff, and it works fairly well.  This has the
additional advantage of actually including the code in the
documentation, if you want it.

I have a suggestion, which is that we try to get the best of both
worlds.  Put clarifications, examples, and so on on the wiki, as the
main documentation.  Have the wiki documentation link to the
function reference, which can be auto-generated from the code.
Ideally, prominently include your e-mail address in the latter in
case someone finds an error.  :)

What do people think?  I'm not suggesting this as an Official
Standard That Everyone Must Comply With, or anything, but does this
seem a reasonable balance of the two setups?

-Robin

-- 
Lojban Reason #17: http://en.wikipedia.org/wiki/Buffalo_buffalo
Proud Supporter of the Singularity Institute - http://singinst.org/
http://www.digitalkingdom.org/~rlpowell/ *** http://www.lojban.org/