JBoss project documentation is generally concerned with instructing the user on how to use the software.

The JBoss Development Process Guide has a Chapter on the roles and responsibilities for creating documentation. According to this guide the following documents should be maintained by each project:

• The product reference guide

• The Javadoc for key APIs and all annotations

• Annotated test cases

• Optional user guides for a specific product

• Optional flash demo for a specific product

Documentation usually exists at varying levels of completeness for different versions of the project.

Javadoc is most readily available as this is generated from the source code.

Most projects also have both a Getting Started Guide and User Guide.

All documentation (apart from Javadoc) is created using DocBook so that it can be converted into many different styles such as single-page HTML, multiple-page HTML and PDF.

A Documentation Guide explains how this is done.

Ideally each general availability release of a project should have a complete set of documentation to accompany it. This has not been achieved in the past due to time constraints and lack of resources. Consequently the documentation pages for most projects have sporadic version numbers associated with the documentation.

We should attempt to fix this as it should be very straightforward to select a version of a project and see all the resources available for it, i.e. binaries, source code, documentation.

Even if the documentation cannot be produced for the release date it should be added afterwards as soon as possible.

New Design

JBoss projects aim to deliver at a minimum the following documents together with each General Availability (GA) release:

1. Javadoc for the public API

2. Reference Guide

Other documentation such as a Getting Started Guide or User Guide can also be provided if necessary to ensure that users can get up to speed quickly and use the software productively.

To see the documentation available for each project you can either use the Documentation portlet on the Resources page and filter by project name, or simply visit each project's main page.

Creating Documentation

All JBoss documentation is created in DocBook so that it can easily be presented in different formats or styles. For example we typically produce single-page HTML, multiple-page HTML and PDF formats of the Reference Guides for users to access at jboss.org. Different styles may be used to make the material more attractive or highlight new major releases.

Since documentation needs to be developed in a structured way, to coincide with each project release, it is stored in a version control repository. This means that to make a contribution to a document you need to submit a patch. Instructions for doing this can be found in the Contribution Portlet on each Project page. If you submit a substantial number of patches or you create a particularly useful piece of documentation then you may be offered commit access to the repository to make your own changes.

Note that this method of contribution is different from the wikis which are typically used to provide information about a project discovered after a release. Any user with a jboss.org account is allowed to make changes to a wiki at any time.