Skip to main content

Don't draw UML diagrams - let the machine do it for you!

Posted by johnsmart on July 24, 2008 at 7:02 PM PDT

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!

Comments

Schemaspy doesn't support JavaDB, what excludes Glassfish demos and other applications based on Derby of using schemaspy :( that is, btw, a fantastic tool.......

he enumeration of tools and techniques is really a good thing, but there is a hidden fallacious on the article suggestions: the effort of producing such automated documentation IS NOT less than the effort of producing it manually.I am tried several types of documentation in the past few years, including docbook, schemaspy and other tools commented in the article, and all the time I tried to use that tool in a real situation, the effort was huge. Ok, you are not locked anymore in external tools, and the ant usage is very comfortable and attractive - but I would register just this small remarkable detail about the effort required to produce good documenation: it continues to be huge :(