Maven: The Complete Reference

10.1. Introduction

Successful software applications are rarely produced by a team of one. When we’re talking about any software worth writing, we’re usually dealing with teams of collaborating developers ranging anywhere in size from a handful of programmers working in a small team to hundreds or thousands of programmers working in a large distributed environment. Most open source projects (such as Maven) succeed or fail based on the presence or absence of well written documentation for a widely-distributed, ad-hoc collection of users and developers. In all environments it is important for projects to have an easy way to publish and maintain online documentation. Software development is primarily an exercise in collaboration and communication, and publishing a Maven site is one way to make sure that your project is communicating with your end-users.

A web site for an open source project is often the foundation for both the end-user and developer communities alike. End-users look to a project’s web site for tutorials, user guides, API documentation, and mailing list archives, and developers look to a project’s web site for design documents, code reports, issue tracking, and release plans. Large open-source projects may be integrated with wikis, issue trackers, and continuous integration systems which help to augment a project’s online documentation with material that reflects the current status of ongoing development. If a new open source project has an inadequate web site which fails to convey basic information to prospective users, it often is a sign that the project in question will fail to be adopted. In other words, for an open source project, the site and the documentation are as important to the formation of a community as the code itself.

Maven can be used to create a project web site to capture information which is relevant to both the end-user and the developer audience. Out of the box, Maven can generate reports on everything from unit test failures to package coupling to reports on code quality. Maven provides you with the ability to write simple web pages and render those pages against a consistent project template. Maven can publish site content in multiple formats including XHTML and PDF. Maven can be used to generate API documentation and can also be used to embed Javadoc and source code in your project’s binary release archive. Once you’ve used Maven to generate all of your project’s end-user and developer documentation, you can then use Maven to publish your web site to a remote server.