This post originated from an RSS feed registered with Agile Buzz
by Joe Walnes.
Original Post: Agiledox
Feed Title: Joe's New Jelly
Feed URL: http://joe.truemesh.com/blog/index.rdf
Feed Description: The musings of a ThoughtWorker obsessed with Agile, XP, maintainability, Java, .NET, Ruby and OpenSource. Mmm'kay?
Chris Stevenson, fellow team-member, has started Agiledox, a small project to collect ideas and tools for automating documentation.
It is typical in agile projects that the code and design changes so quickly that the documentation (if any) never keeps up. We are using Agiledox on our current project to help give us all a high-level map of what the system does at all times.
When practicing collective code ownership it is vital that all developers know how the entire system works, not just their bit (they have no bit). With bigger systems that are constantly evolving it is unlikely that any one person knows how it all works, so it's nice to have a higher level roadmap of the system to look around before drilling into some code. Of course, this is no substitute for good communication - but it helps.
The first deliverabe in Agiledox is Testdox . It autogenerates documentation from testcases. Wow! How?
Simple. All it does is look at a test class and all the test method names and convert them from camal case Java names to sentences. Genius!
You may laugh, as I did. But I was amazed at what it produced for our project.
There's a catch though. It worked for us because we are well disciplined in the way we write tests. For a start, we were already in the habit of writing test case method names that describe what a class should do rather than what all the methods are. Don't moan that this low emission petrol isn't great when you're trying to put it in a deisel engine.