← RichFaces Documentation Plan

Phase 1: Information Plan

Purpose of the Project

The RichFaces 4.0 Project aims to produce a more professional and consistent version of the RichFaces components. In addition to support for JSF 2.0, RichFaces 4.0 standardizes the components' names and interfaces and simplifies their implementation and usage.

Purpose of the Documentation

A crucial part of presenting a more professional RichFaces product is the inclusion of a comprehensive suite of documentation and usage guides. The new documentation will be written in clear, formal English, and presented in the Red Hat and JBoss corporate style.

Usability Goals for the Documentation

The Documentation needs to provide a complete understanding of RichFaces to the audience. The audience must be able to easily follow the purpose, usage and limitations of each component, as well as how best to implement them in a project.

Product Description

RichFaces is a component library for JavaServer Faces built on the open-source Ajax4jsf framework. It allows easy integration of Ajax capabilities into enterprise application development.

In addition to expanding the number of visual ready-to-use components of the Ajax4jsf framework, RichFaces also implements the "skinnability" feature, including a large number of predefined skins to manage the look-and-feel of an application.

Audience Profile

The audience for the documentation will primarily be developers looking to use RichFaces technologies in their enterprise web applications. These developers will either be experienced RichFaces users who are upgrading to the latest version, or developers who have had no experience with previous versions of RichFaces.

Audience Assumptions

The audience will have at least a basic technical background and at least some understanding of web application technologies.

Goals of the Audience

Audience goals include:

• successfully implementing RichFaces components in their applications.
• troubleshooting RichFaces applications.
• learning what has changed from previous versions of RichFaces, and how to update existing projects.

Task Description

Development with components:

• installation
• choosing a suitable component for the task
• configuring the component
• referring to examples or demonstrations involving the component

Troubleshooting:

• determining the problem
• finding a solution to the problem

Version changes:

• gaining an overview of the changes
• updating an existing project to the new version

User/Task Matrix

Design Implications

The user and task analysis implies that the Development and Troubleshooting tasks should be mostly written with the novice user in mind, who has little or no prior experience with the RichFaces suite. As long as the language is not too simplistic, experienced users will still benefit from this approach. However the documents dealing with changes between versions can be written solely for experienced users.

Documentation Strategies and Concerns

To determine a suitable approach, potential users of RichFaces 4.0 will be consulted, primarily through the established RichFaces and JBoss forums. Jay Balunas also recommended Practical RichFaces by Max Katz as a good reference book; it will prove useful in developing strategies and approaches as well.

The revision process will likely not affect the deliverables hugely, as for the most part the RichFaces 4.0 project is starting from an established base and the fundamental design is unlikely to undergo massive changes. In fact, a public alpha of RichFaces 4.0 is currently available, so the project is already significantly advanced.

As alpha and beta versions of the RichFaces product become available, the community will also look to accompanying documentation, and as the documentation gets completed and reviewed along with the software, additional feedback from users will likely be available.

The documents will be initially written in US English, and translation and localization will be required as is usual for Red Hat product documentation.

Media Selection

The deliverables will be produced through Publican, and can be made available as single HTMLs, multiple HTMLs, and PDF files.

Existing Products

The following documentation products exist for previous versions of RichFaces.

Deliverables

Content from the existing products above will be rewritten and composed as the following new deliverables:

Constraints

The major constraint is due to the development team being located in Minsk, Belarus, the management team being located in the USA, and the content authoring being done in Brisbane, Australia. Regular meetings and communications will ensure this constraint is negligible.

Project Plan

Scope

This project plan covers the preparation and production of all documents associated with RichFaces 4.0

Items not covered in the project but which may affect production include:

• writing and updating RichFaces articles on Wikipedia (mostly to be done by development team)
• writing and updating articles on JBoss Wiki pages
• writing articles and announcements on popular community websites (mostly to be done by development team)
• possibly writing articles for a RichFaces blog (old blog at http://jbossrf.blogspot.com, new blog possibly will be at http://in.relation.to)

Estimate of Hours

For entire project
17 August 2009 to 5 March 2010
= 140 weekdays

Phase 1: Information Planning
10% = 14 days

Phase 2: Content Specification
20% = 28 days

Phase 3: Implementation
50% = 70 days

Phase 4: Production
19% = 27 days

Phase 5: Evaluation
1% = 1 day

Breakdown by book (Phase 3)
= 70 weekdays

Migrating to RichFaces 4.0
~20% = 14 days

Developer Guide
~30% = 21 days

Component Reference
~30% = 21 days

Component Development Kit Guide
~20% = 14 days

Schedule of Milestones

Translation Plan

During implementation, considerations for localization will be made. A final review at the start of Phase 4 will ensure the documents are suitable for translation.

Production Plan

The various books will be made available in HTML, single-HTML and PDF form on redhat.com.

Usability and Validation Plan

Throughout the project lifetime, alpha and beta releases of RichFaces will be made available to the community. Documentation will gradually be packaged with these releases, so that usability and validation can be conducted by actual product users.

Maintenance Plan

RichFaces development will be ongoing even after the release of 4.0. For future minor versions, it is expected that the 4.0 documentation is updated and revised rather than being rewritten. Only the Upgrading to RichFaces 4.0 book will need to be completely rewritten.