[Rails-devel] Documentation (was: migrating away from cvs)

[Freek D. <sf_...@ma...>]

Rick Westerman wrote:

>    Now what is missing is an overall view of what the various files do 
> and what helper programs have been created.  I was working on such a 
> document but, alas, despite the winter weather I have not had time to 
> follow through on said document.

Hi Rick,

Care to collaborate on such documentation? I presume the audience is 
developers rather than users for now. I asked a few questions, and got 
some great answers by Erik and Brett. However, some things are not 
obvious, or outdated.

What do you like to improve?

1. Update the visio file with the class hierarchy (which seems outdated 
at the moment)

2. Document the folder structure. In most projects, the folder structure 
seems to be grouped like this:
* source code
* data files for inclusion in the program
* tools and documentation to be included with the program
* tools and scripts for creating various builds
* build folder (created by the build environment)

However, the current rails folder structure does not follow this 
approach. For example the tiles folder contains both tools for 
generation as well as the final output, even though I had expected to go 
in the "data" folder as I had expected.

3. Document the build process. I found that the Eclipse build process is 
quite different from the ant build process, although they use the same 
folders. It is possible to integrate these (both by calling ant from 
within Eclipse or using the incremental Java builder from ant). However, 
I am not sure if it would gain us anything by integrating these 
processes, so I wonder if we should either integrate it more or 
differentiate it (using different folders; I found that eclipse 
sometimes does not register changed files created by an ant build).
However, I did put this on hold for now (I got a little girl at home, 
and my wife started working again last week, so free time is a scare 
resource right now).

PS: Out of curiosity, I still use TextMate (a Mac editor) and ant to 
build stuff. However, I am also using eclipse for debugging. Do you use 
any debugging, and if so, using what tools?


Regards,
Freek