I’m a big believer in project transparency. I also like to utilize a hub and spoke model where a central project intranet site is available for the team to pull from rather than relying on emails or file stores. A simple wiki with a landing page is all you really need. Especially if your client is phobic about using hosted tools (e.g., Mingle/Campfile). With a team portal, keeping the content up to date should be automatic if the content is derived from your code. Wouldn’t it be nice if documentation about your project was always up to date? Wouldn’t it be even nicer if this documentation could include easy to digest change logs, list of todos/notes and other information? Well, this post will show you how easy it is to do just that.

What am I talking about? I’ll use the work I’m currently doing for my client to illustrate. We have a rails RDOC oriented README_FOR_APP page that has includes for things like change log, metrics, notes/todos and the like. These elements are built by our cruise control process (we simply added a few extra statements in the rake file that cruse fires off).
Ok so how hard is this to do?

The answer is it is very simple. Here is the blow by blow…

1. set you project up to run under cruise control.

2. By default, cruise wants to run your rake test task. So you need to create a new super task for cruise to run. In you project Rakefile, add a new build task to run your tests and then generate the documentation.

3. Edit your doc/README_FOR_APP with useful information. When you want to include some of the generated files like the changelog, you simply add :include:filename. As an example, here is the project readme file…

= Some Project - Prototype
You can visit the current prototype by going to our
demo [http://url.to.the.site/] site.

== Notes

:include:notes.txt

== Statistics

:include:stats.txt

(LOC = Lines of Code)

== CHANGELOG

:include:CHANGELOG

Pretty simple…

4. Modify cruise to use your new rake task.

5. Set up a symlink in project facing web server directory to point to your cruise directory. For example in ~dhainlin/public_html I did something like ln -s /var/cruise/cruisecontrolrb-1.2.1/projects/sample/work sample which created a directory called sample. This essentially creates a permalink for your project documentation.

6. Browse to your new docs and enjoy fresh, always current information.

Hope this is useful. If you have questions or problems, let me know.