From: Jim Cain <list@...>
Date: 2003-07-11T14:15:27+09:00
Subject: Re: A Ruby XSL stylesheet for DocBook?

Austin Ziegler wrote:

> On Fri, 11 Jul 2003 11:35:31 +0900, Jim Cain wrote:
> 
>> Austin Ziegler wrote:
>> 
>>> On Fri, 11 Jul 2003 08:54:59 +0900, Jim Cain wrote: Might it be
>>> easier to document the library with rdoc? You can cause it to
>>> output to XML.
>> 
>> Perhaps, but I prefer not to clutter my source code with an 
>> abundance of commends. I would ultimately like to have more than 
>> just an API reference for my library, and I don't feel that the 
>> source code is the place for all that text.
> 
> 
> Odd. I do consider the source the place for all that text -- I often
> look at the source code of what I'm using to see how I should be
> using it. Plus, by having the source and the documentation together
> (at least for English, in my case), I don't neglect to do the
> documentation or forget to do it. I just document everything.
> Sometimes this has also helped me identify when I've made things
> public when I meant them to be private.
> 
> [snip]
> 
> I program against Oracle a lot, and I'm not sure how much I'd see
> myself using an application/library that I can't drop into the
> documentation quickly and easily, which I can with many other Ruby
> apps. I don't necessarily want to fire up a browser session when I'm
> coding.

Maybe I'm strange, but I just like having code and doc in separate 
places. I like being able to absorb the code at a glance, and for me 
embedded documentation just gets in the way. Also, I'm rather into how 
my code "looks," and embedded docs detract from that "look." Perhaps I'm 
the only one who's that way.

When I'm coding, I typically have Mozilla open for reference purposes, 
most often with multiple docs (the browser tabs are perfect for this). 
But even with embedded docs, the source of the library (and therefore 
its docs) would be open in a separate window from where I'm coding, 
unless I'm editing the library itself.