John is an experienced consultant specialising in Enterprise Java, Web Development, and Open Source technologies, currently based in Sydney, Australia. Well known in the Java community for his many published articles, and as author of Java Power Tools and Jenkins: The Definitive Guide, and founder of the open source Thucydides Automated Acceptance Test Library project, John helps organisations to optimize their Java development processes and infrastructures and provides training and mentoring in agile development, automated testing practices, continuous integration and delivery, and open source technologies in general. John is the CEO of Wakaleo Consulting, and runs several Training Courses on open source Java development tools and best practices. John is a DZone MVB and is not an employee of DZone and has posted 125 posts at DZone. You can read more from them at their website. View Full User Profile

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

07.25.2008
| 8744 views |
  • submit to reddit

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!

Published at DZone with permission of John Ferguson Smart, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Emmanuel Hugonnet replied on Fri, 2008/07/25 - 8:20am

Hi,

I think Apiviz is in the same spirit and seems easier to integrate than UMLGraph even if it is based on the same solution (Graphiz).

Emmanuel

Francis Perreault replied on Fri, 2008/07/25 - 11:59am

Doxygen is pretty nice too for annotated documentation!

Anders Hybertz replied on Mon, 2008/07/28 - 12:56am

For sequence diagrams I have been using mscgen (http://www.mcternan.me.uk/mscgen/) - nice and simple.

 Doxygen even have tags, which supports your inline mscgen comments.

Romen Law replied on Mon, 2008/07/28 - 6:14pm

I had been using Together (since Control Center v5) until Borland took it over. I love TCC's real-time round-trip engineering features and its template based documentation generation capability. Too bad, after Borland took over, it became lagged behind, bloated and really slow, so I gave it up. I have yet to find anything that matches TCC's features and usability.

cheers

romen

John Brugge replied on Fri, 2008/08/08 - 4:20pm

Those are all great tools, which I agree make documentation much more believable and trusted - when it is generated, it is up to date.

 A few other interesting doc tools to consider:

  • DBDoclet: a Javadoc Doclet that will do the DocBook transformations for you.
  • BeanDoc: for documenting Spring configurations. 
  • JUnitPDFReport: generate PDFs of test results.
  • Linguine Maps: can do Ant diagrams like Grand, as well as Hibernate mapping diagrams.

And in the spirit of making even this automation easier, there is Glean, an Ant script that lets you add these types of tools to your build with less hassle.

 Thanks,

John

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.