Separating Developer Reports from User Documentation

After adding a report, there’s something subtly wrong with the project Web site. On the entrance page there are usage instructions for Proficio, which are targeted at an end user, but in the navigation there are reports about the health of the project, which are targeted at the developers.

This may be confusing for the first time visitor, who isn’t interested in the state of the source code, and an inconvenience to the developer who doesn’t want to wade through end user documentation to find out the current state of a project’s test coverage.

This approach to balancing these competing requirements will vary, depending on the project. Consider the following

• The commercial product, where the end user documentation is on a completely different server than the developer information, and most likely doesn’t use Maven to generate it;

• The open source graphical application, where the developer information is available, but quite separate to the end user documentation;

• The open source reusable library, where much of the source code and Javadoc reference is of interest to the end user.

To determine the correct balance, each section of the site needs to be considered; in some cases down to individual reports. Table 6-1 lists the content that a project Web site may contain, and the content’s characteristics.

Table 6-1: Project Web site content types

In the table, the Updated column indicates whether the content is regularly updated, regardless of releases. This is true of the news and FAQs, which are based on time and the current state of the project. Some standard reports, like mailing list information and the location of the issue tracker and SCM are updated also. It is also true of the project quality and vitality reports, which are continuously published and not generally of interest for a particular release. However, source code references should be given a version and remain unchanged after being released.

The situation is different for end user documentation. It is good to update the documentation on the Web site between releases, and to maintain only one set of documentation.

Features that are available only in more recent releases should be marked to say when they were introduced. It is important not to include documentation for features that don’t exist in the last release, as it is confusing for those reading the site who expect it to reflect the latest release.

The best compromise between not updating between releases, and not introducing incorrect documentation, is to branch the end user documentation in the same way as source code. You can maintain a stable branch, that can be updated between releases without risk of including new features, and a development branch where new features can be documented for when that version is released.

The Distributed column in the table indicates whether that form of documentation is typically distributed with the project. This is typically true for the end user documentation. For libraries and frameworks, the Javadoc and other reference material are usually distributed for reference as well. Sometimes these are included in the main bundle, and sometimes they are available for download separately.

The Separated column indicates whether the documentation can be a separate module or project. While there are some exceptions, the source code reference material and reports are usually generated from the modules that hold the source code and perform the build. For a single module library, including the end user documentation in the normal build is reasonable as it is closely tied to the source code reference.

However, in most cases, the documentation and Web site should be kept in a separate module dedicated to generating a site. This avoids including inappropriate report information and navigation elements.

This separated documentation may be a module of the main project, or maybe totally independent. You would make it a module when you wanted to distribute it with the rest of the project, but make it an independent project when it forms the overall site with news and FAQs, and is not distributed with the project.

It is important to note that none of these are restrictions placed on a project by Maven. While these recommendations can help properly link or separate content according to how it will be used, you are free to place content wherever it best suits your project.

In Proficio, the site currently contains end user documentation and a simple report. In the following example, you will learn how to separate the content and add an independent project for the news and information Web site.

The current structure of the project is shown in Figure 6-3:

Figure 6-3: The initial setup

The first step is to create a module called user-guide for the end user documentation. In this case, a module is created since it is not related to the source code reference material. This is done using the site archetype :

C:\mvnbook\proficio> mvn archetype:create -DartifactId=user-guide \           

-DgroupId=com.exist.mvnbook.proficio \ 
-DarchetypeArtifactId=maven-archetype-site-simple

This archetype creates a very basic site in the user-guide subdirectory, which you can later add content to. The resulting structure is shown in Figure 6-4.

Figure 6-4: The directory layout with a user guide

The next step is to ensure the layout on the Web site is correct. Previously, the URL and deployment location were set to the root of the Web site: http://www.exist.com/web/guest/products/resources. Under the current structure, the development documentation would go to that location, and the user-guide to http://www.exist.com/web/guest/products/resources/user-guide.

In this example, the development documentation will be moved to a /reference/version subdirectory so that the top level directory is available for a user-facing Web site.

Note: Adding the version to the development documentation, while optional, is useful if you are maintaining multiple public versions, whether to maintain history or to maintain a release and a development preview.

First, edit the top level pom.xml file to change the site deployment url:

<distributionManagement>
  <site>
    [...]
    <url>
      scp://exist.com/www/library/mvnbook/proficio/reference/${pom.version}
    </url>
  </site>
</distributionManagement>

Next, edit the user-guide/pom.xml file to set the site deployment url for the module:

<distributionManagement>
  <site>
    <id>mvnbook.site</id>
    <url>
      scp://exist.com/www/library/mvnbook/proficio/user-guide
    </url>
  </site>
</distributionManagement>

There are now two sub-sites ready to be deployed:

• http://exist.com/www/library/mvnbook/proficio/reference/${pom.version}

• http://exist.com/www/library/mvnbook/proficio/user-guide

Important: You will not be able to deploy the Web site to the locations scp://exist.com/www/library/mvnbook/proficio/reference/${pom.version} and scp://exist.com/www/library/mvnbook/proficio/user-guide. They are included here only for illustrative purposes.

Now that the content has moved, a top level site for the project is required. This will include news and FAQs about the project that change regularly.

As before, you can create a new site using the archetype. This time, run it one directory above the proficio directory.

C:\mvnbook> mvn archetype:create -DartifactId=proficio-site \      
-DgroupId=com.exist.mvnbook.proficio \     
 -DarchetypeArtifactId=maven-archetype-site-simple

The resulting structure is shown below:

Figure 6-5: The new Web site

You will need to add the same elements to the POM for the url and distributionManagement as were set originally for proficio-site/pom.xml as follows:

[...]
<url>http://www.exist.com/web/guest/products/resources</url>
[...]
<distributionManagement>
  <site>
    <id>mvnbook.website</id>
    <url>scp://exist.com/www/library/mvnbook/proficio</url>
  </site>
</distributionManagement>
[...]

Next, replace the src/site/apt/index.apt file with a more interesting news page, like the following:

-----
Proficio
-----
Joe Blogs
 -----
23 July 2007
-----

Proficio

 Proficio is super.

 * News

   * <16 Jan 2006> - Proficio project started

Finally, add some menus to src/site/site.xml that point to the other documentation as follows:

[...]
<menu name="Documentation">
  <item name="User's Guide" href="/user-guide/" />
</menu>

<menu name="Reference">
  <item name="API" href="/reference/1.0-SNAPSHOT/apidocs/" />
  <item name="Developer Info" href="/reference/1.0-SNAPSHOT/" />
</menu>
[...]

You can now run mvn site in proficio-site to see how the separate site will look. If you deploy both sites to a server using mvn site-deploy as you learned in Chapter 3, you will then be able to navigate through the links and see how they relate.

Note: Note that you haven’t produced the apidocs directory yet, so that link won’t work even if the site is deployed. Generating reference documentation is covered in section 6.6 of this chapter.

The rest of this chapter will focus on using the developer section of the site effectively and how to build in related conditions to regularly monitor and improve the quality of your project.