What is documentation?
- Documentation
- The process of documenting knowledge
Documentation for software developers are documents that describe how to run or use the artifact/project. Typically documentation provides any exposed settings, their uses and default values. In addition information about integration, entry and exit points such as JMS queues, JMX MBeans, DataSource objects and/or JNDI variables in order to run and use the artifact. There are many programs and standards to produce this level of documentation including MS word, Sharepoint, doxygen, Latex, Wiki, markdown, textile, etc.
Outside of artifact specific documentation team leads, architects and project managers usually ask for JavaDocs to be included. JavaDocs, if combined with Maven provide more documentation for your IDE and better information for the consumers of your artifact. Other important documentation includes testing reports, test coverage, static analysis tools, dependencies of your artifact, change log and issue management such as Jira or Bugzilla.
Why create docs?
The best reason to care about documentation is to provide information for external developers and team members outside of the project's development environment. Documentation can be utilized inside of IDEs as well and face it, how many times do you wish you had sources and/or JavaDocs for a dependency when you were programming or to send back an email with the site docs so someone can be self-served rather than take your time.
Problems with traditional documentation
The largest complaint with traditional documentation is that it becomes stale over time. Time is never allocated in a project&dagger to provide or update documentation and stale docs can lead a developer or team down many wrong paths leading to hours or days of misinformation lead rabbit holes.
† Agile, SCRUM and Lean processes should allow time to be built-in to handle technical debt like documentation, even thought it is called the "necessary evil". Read more here
Secondly, developers are the ones who are askedforced to maintain the documentation and typically developers are not great in the writing department and unless segments of the documentation process are automated, developers are people and we forget.
Last major problem with traditional documentation is that it is typically not automated and is an extra step during the build/release cycle. Any process in the build cycle that is not automated and tested will break down at some point. Humans are great at abstract thinking, not repetitive processes.
Solution to the problems
As stated above, the main problems are developers maintaining all documentation and documentation that is either built outside of the immediate environment or is not automated. This is where Maven's site documentation comes in. Maven was built with the understanding that documentation needs to be automated and has been progressively improved throughout updates to the maven project.
The most common case for Maven site docs is to deploy generated documentation to an external web server via SCP, FTP, WebDAV or SFTP. The site plugin takes use of Apache's Wagon library for secure transfer of docs. Most of the time the site docs are generated during the release† or deploy phases and generate on the verify phase.
† Release isn't a phase in maven, it is a plugin, but it is considered a best practice when publishing versioned artifacts to a maven repositoryMaven 3 vs Maven 2
Maven decided to change the way that reports were collected and generated in between the Maven 2 and Maven 3 releases. In Maven 2, the POM would have a section called >reports< where plugins that handled ReportSet would be handled. In Maven 3, there is now a plugin that handles and collates the ReportSets instead of Maven handling it. The plugin is called maven-project-info-reports-plugin and documentation can be found here.
Sources for this series of blog post
I have provided a link to a fully functional multi-module maven project that publishes to both http://mike-ensor.github.com/multi-module-site-doc-project/index.html and locally to ${env.HOME}/sitedocs/${project.artifactId}.
https://github.com/mike-ensor/multi-module-site-doc-project.
Maven 3 Site Docs
There are two important elements with respect to site docs for Maven. Plugins, which generate ReportSet elements and Site Doc/Descriptors.
Plugins
Plugins are an important part of the documentation process and will typically run throughout the maven build lifecycle generating artifacts for the plugin phase that generates the ReportSet. A good example would be the maven-checkstyle-plugin. The plugin is typically bound to the process-resources or packakge phases so that developers know they have a checkstyle violation early in the build lifecycle. The plugin generates a checkstyle.xml document that is then used in the site phase by the maven-project-info-reports-plugin to generate a checkstyle report page.
Maven Site Plugin
The maven-site-plugin is the main plugin that is used to crate all site documentation. Each plugin that produces and/or consumes a ReportSet will need to be configured inside of the <reportPlugins> section. NOTE: This is where the Wagon plugin is set as a dependency. The Site plugin will use the <distributionManagement><site> line to determine where the site docs are to be published (SCM, WebDAV, SFTP, etc)
<plugin> <artifactId>maven-site-plugin</artifactId> <version>${plugin.maven-site.version}</version> <dependencies> <dependency><!-- add support for ssh/scp --> <groupId>org.apache.maven.wagon</groupId> <artifactId>wagon-ssh</artifactId> <version>${plugin.wagon-ssh.version}</version> </dependency> </dependencies> <configuration> <attach>true</attach> <reportPlugins> <plugin> ... ... Plugins go here .... </plugin> </reportPlugins> <attach>true</attach> </configuration> </plugin>
Maven Project Info Report Plugin
The maven-project-info-report-plugin is the main plugin used by the maven-site-plugin that Maven 3 utilizes to collate and produce the common site reporting docs for the artifact
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-project-info-reports-plugin</artifactId> <configuration> <dependencyDetailsEnabled>false</dependencyDetailsEnabled> <dependencyLocationsEnabled>false</dependencyLocationsEnabled> </configuration> <!-- simpler configuration without reportSets available for usual cases --> <!-- distribution-management, index, dependencies, help, issue-tracking, plugins, cim, license, dependency-management, mailing-list, project-team, dependency-convergence, scm, plugin-management, modules, summary --> <reports> <report>summary</report> <report>dependencies</report> <report>project-team</report> <report>issue-tracking</report> <report>scm</report> <report>cim</report> <report>modules</report> <report>plugins</report> </reports> </plugin>
Take a quick look at the types of reports that are automatically generated using the maven-project-info-reports-plugin. Many of these automatically generated reports provide additional information on top of the redundant information provided by the below listed plugins.
List of automatically provided reports
- distribution-management
- index
- dependencies
- help
- issue-tracking
- plugins
- cim
- license
- dependency-management
- mailing-list
- project-team
- dependency-convergence
- scm
- plugin-management
- modules
- summary
Common Plugins
Checkstyle - maven-checkstyle-plugin – Provides static analysis on source files – NOTE: Checkstyle needs to be run during build AND report phases
Example report plugin
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-checkstyle-plugin</artifactId> <configuration> <skip>${checkstyle.skip}</skip> <configLocation>${checkstyle.configUrl}</configLocation> <failsOnError>false</failsOnError> <enableRulesSummary>true</enableRulesSummary> <includeTestSourceDirectory>true</includeTestSourceDirectory> </configuration> </plugin>
NOTE: A best practice is to provide a flag to enable/disable the plugin on a project-by-project basis. Also, notice the failsOnError, this will ensure that the plugin will produce an artifact on error and present that to the user.
FindBugs - maven-findbugs-plugin – Provides static analysis on source files – Plugin does not need to be run outside of report phase
Example report plugin
<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>findbugs-maven-plugin</artifactId> <configuration> <skip>${findbugs.skip}</skip> <xmlOutput>true</xmlOutput> </configuration> </plugin>
NOTE: A best practice is to provide a flag to enable/disable the plugin on a project-by-project basis. Also, notice the failsOnError, this will ensure that the plugin will produce an artifact on error and present that to the user.
Cobertura - maven-cobertura-plugin – Provides code coverage during Unit Test (test) phase. NOTE: Must be run during build AND during reporting phases
Example report plugin
<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>cobertura-maven-plugin</artifactId> <configuration> <skip>${cobertura.skip}</skip> </configuration> </plugin>
NOTE: A best practice is to provide a flag to enable/disable the plugin on a project-by-project basis. Also, notice the failsOnError, this will ensure that the plugin will produce an artifact on error and present that to the user.
PMD and CPD - maven-pmd-plugin – Provides static analysis (PMD) and code duplication/cut-copy-paste detection for artifact. Read more about the PMD plugin here.
Example report plugin
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-pmd-plugin</artifactId> <configuration> <skip>${pmd.skip}</skip> <targetJdk>${maven.compiler.source}</targetJdk> <sourceEncoding>${project.build.sourceEncoding}</sourceEncoding> <minimumTokens>100</minimumTokens> <rulesets> <ruleset>${maven-pmd-plugin.configLocation}</ruleset> </rulesets> <failOnViolation>false</failOnViolation> </configuration> </plugin>
Surefire and Failsafe - maven-surefire-report-plugin – Creates reports based on tests cases for unit tests and optionally integration tests. NOTE, This is a different plugin than the maven-surefire-plugin, this is the report plugin that operates on the ResultSet for both Surefire and Failsafe. Both Surefire and Failsafe must be run during the build for this plugin to generate reports.
Example report plugin
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-report-plugin</artifactId> <reportSets> <reportSet> <id>integration-tests</id> <reports> <report>report-only</report> <report>failsafe-report-only</report> </reports> </reportSet> </reportSets> </plugin>
JavaDoc - maven-javadoc-plugin – Bundles JavaDocs into the reporting structure. NOTE, this does not need to be run during the standard build, only during the reporting phase
Example report plugin
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <configuration> <skip>${javadocs.skip}</skip> <failOnError>false</failOnError> </configuration> </plugin>
JXR - maven-jx-plugin – Builds cross-link information for classes. Checkstyle, PMD, FindBugs, JavaDocs and various other plugins can utilize the JXR configuration. NOTE, this plugin must be run at an early place in the Maven lifecycle (suggest process-resources) in addition to the sitedoc plugin section.
Example report plugin
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jxr-plugin</artifactId> <configuration> <aggregate>true</aggregate> </configuration> </plugin>
Useful Plugins
Other handy plugins to use for site documentation include:
- Taglist – Searches source code for specific words like @TODO and FIXME, then collates them into a report per project — http://mojo.codehaus.org/taglist-maven-plugin/
- Versions – Uses maven central and/or local mirror to look up each dependency, project properities and plugin versions, then produces a report with what can be updated both minor and major updates — http://mojo.codehaus.org/versions-maven-plugin/
- Changelog - Uses SCM listed in the distributionManagement section to pull in a simple history for each file; listing most changed files, top contributors and links up changes with web-based SCM tool like github or web-svn — http://maven.apache.org/plugins/maven-changelog-plugin
- Changes - Integrates with Jira, Trac or Bugzilla (or any changelist.xml produced by an Issue Management system) and displays what bugs have been updated in between the current and previous release — http://maven.apache.org/plugins/maven-changes-plugin/
End of Part 1
The next post will cover the developer portion of the documentation; more specifically covering XDoc and APT. The site documentation is robust and the next post will show how to program some of the XDoc portions of the docs by leveraging Velocity templates.
The last part of this blog post will cover multi-module projects. In addition, that post will show how to deploy site-docs to a Github Pages so you can have site docs at http://<username>.github.com/<your-project>.