Re: [Chicken-users] Comprehensive documentation rewrite

[Shawn Rutledge]

On Feb 13, 2008 1:44 AM, Peter Bex <address@hidden> wrote:
> 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.

That sounds like something that could be fixed in your editor, in
theory... e.g. the emacs mode could elide such comments to one line by
default, and then you can unfold it if you want to see the whole
thing.  I'm not an emacs user though.  (Maybe some day...)

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

It's better to work smart, not hard.  That means start by building the
tools, to minimize the tedium.  A good example (outside the software
domain) would be the human genome project...  But if you do it the
hard way, then you will be even less inclined to ever do it again,
even if the result was suboptimal and still needs improvement.
Quality results from continuous improvement, not a one-pass "get it
right and call it done".