Don't Draw UML Diagrams - Let The Machine Do It For You!

My friend Paul Duvall, principal author of that great Continuous Integration reference "Continuous Integration", has written an excellent article on automating the process of generating technical documentation in "Automation for the people: Pushbutton documentation". For most developers, technical documentation is a pain to do, and is rarely complete or up to date, if it is ever done at all. However, much of what needs to be documented - class diagrams and database DDLs, for example - can be extracted directly from the source code.

In this article, he discusses how to generate Javadocs embedded with UML diagrams using UMLGraph, how to document your database with entity-relationship diagrams using that brilliant but little known tool SchemaSpy, and how to graphically document your Ant script using Grand. A picture tells a thousand words, as they say, and this is very true in the IT industry, where a few diagrams can do wonders for your understanding of a system.

Of course, tools will never be able to explain why you did things in a particular way, or what the intention behind it all is - so they are no excuse not to write good comments. Indeed, they rely on good comments to be really useful. Paul also talks about how to add steroids to your comments with DOxygen, and also how to write user documentation using DocBook.

All great stuff!