From: Aredridel <aredridel@...>
Date: 2004-02-23T13:18:14+09:00
Subject: Docs [Was Regarding PLD RPMs of rake and ruby-dbi and a plea to packagers]

On Mon, Feb 23, 2004 at 09:44:50AM +0900, Charles Comstock wrote:
> > ... It may be as unpleasant as documentation, but that doesn't mean
> > it doesn't need to be done.
> 
> Documentation shouldn't be considered unpleasent.  If you go to the
> trouble of making something to share, it's common curtesy to at least
> give basic instructions on it's use.  Yes most of us are programmers
> not tech writers, but we should take pride in explaining what our
> creation is capable of.

Wholeheartedly agreed.

Thankfully, we have some very fine (and unobtrusive) tools with Ruby:
rdoc is a piece of work whose subtlety I'd love to see imitated.

In addition to rather liking test-first coding (which I'm just now
getting into), I like document-first coding.  Write tests (expect them
to fail), write docs (expect them to be more complete than the code),
then write code that fulfils the tests and matches the docs.

I think that's why the Exim MTA is as successful as it is.  In addition
to being wildly flexible, it's well-documented, because it's spec'd in
advance. It should be a standard practice, and is one I'm trying to
develop in myself.

Ari