Re: [Chicken-users] Comprehensive documentation rewrite

[Peter Bex]

On Wed, Feb 13, 2008 at 09:18:20AM +0100, felix winkelmann wrote:
> > 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.

Yeah, and the same goes for the horrible hack known as rdoc.  Rdoc is
basically Doxygen without semantic markup.

Another problem of 'rdoc-like' documentation is that you end up having to
wade through piles and piles of documentation in the code when you're
looking for something.  Just look at the Rails code, some classes start
with several *pages* of text.  Sometimes even functions have pages of text
preceding them.  It makes reading the code awfully hard.
Besides, even with so much documentation, stuff is *still* not documented
properly and it's often hard to find docs on stuff because it's all
hidden away.

> Another effect is that documentation is structured to fit the doc-generating
> tool, instead of being easy to access for users.

Docs are hard to maintain and code is hard to maintain when you stick them
all in one big pile.

> 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.

I like it too, but it's not rich enough to express the semantics.
However, with the proper extensions to the syntax this problem can be fixed.

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

That's why there shouldn't be "all these" doc overhauls, there should
be just one, resulting in proper documentation.

Cheers,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth

pgphomLyruekT.pgp
Description: PGP signature