A perfectly designed project is meaningless without good documentation to back it up. No matter how well it is designed, without a path to lead new developers up to your stride you may as well write spaghetti code. Without documentation to explain to users how one goes about using your project it will never gain popularity beyond a small group of people (often the developers themselves…and perhaps their moms).

Some proponents of agile develoment would have it that the source code itself should provide sufficient technical documentation for all purposes. There may be some merit in this statenent. After all, the source code is always up to date. However, looking at the code alone is a difficult way to understand an application. Comments are still essential to explain why a class does what it does: lines of code do a poor job of explaining business logic and design decisions. This is why it is still a good idea to document your classes in as much detail as reasonably possible.

Tools can help automate, complete, and enrich your documentation process. Tools such as Javadoc, SchemaSpy, and Doxygen can be used to produce decent, up-to-date, accurate, and reasonably usable online documentation, including (for the latter two) graphical database models and UML diagrams. With a few well-placed comments, and combined with a few strategic vision documents, this sort of automatically generated documentation might be just enough to help a new developer understand the architecture of your product. And by fully integrating the documentation generation process into the SDLC, you can guarantee permanently available and up-to-date technical documentation for the whole team.

In this part, we look at several tools that can help you automatically generate up-to-date documentation about your project. Maven 2 builds documentation generation as a cornerstone of a comprehensive software development management process. We will take a detailed look at how you can get the most out of your Maven-generated web site.

We will also look at three tools that can be used independently of Maven 2 to generate high-quality graphical representations of your project design and architecture: SchemaSpy for database models, and Doxygen and UmlGraph for UML-based source code documentation.