Re: [Chicken-users] Comprehensive documentation rewrite

[felix winkelmann]

On Feb 12, 2008 10:16 PM, Shawn Rutledge <address@hidden> wrote:
> On Feb 12, 2008 10:13 AM, Tobia Conforto <address@hidden> wrote:
> > My idea is to devise a "smart" document format, preferably s-expr
> > based (maybe SSAX-based if nothing better comes to mind) and convert
> > every piece of Chicken API documentation to that format: both for eggs
> > and for the base system.  This includes any relevant SRFIs that are
> > part of Chicken or of some eggs.
>
> I like the idea of being able to put the documentation into the code;
> something like Doxygen is needed for Scheme.  I think it's not the
> first time such an idea has been proposed, but I don't know much about
> what has been tried.
>

In my experience separating the documentation from the code leads
in the end to more consistent information. I've seen too much doxygen
generated "documentation heaps" with no obvious start or beginning.
Another effect is that documentation is structured to fit the doc-generating
tool, instead of being easy to access for users.

I happen to like svnwiki syntax. It's easy to use, non-obstructive and
we have all the infrastructure to convert it into other formats.

Besides, all these doc overhauls just eat up developer time...


cheers,
felix