RichFaces 4.0 Docs Information Plan

Version 9

    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

    TasksExperienced UsersNovice Users
    Development810
    Troubleshooting810
    Version changes101

    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.

    ProductSVN LocationPublished Location
    Component Developer Kit Guidehttp://anonsvn.jboss.org/repos/richfaces/branches/community/3.3.X/docs/cdkguide/http://docs.jboss.org/richfaces/latest_3_3_X/en/cdkguide/
    FAQhttp://anonsvn.jboss.org/repos/richfaces/branches/community/3.3.X/docs/faq/http://www.jboss.org/file-access/default/members/jbossrichfaces/freezone/docs/devguide/en/faq/faq.html
    Migration Guidehttp://anonsvn.jboss.org/repos/richfaces/branches/community/3.3.X/docs/migrationguide/http://docs.jboss.org/richfaces/latest_3_3_X/en/migrationguide/
    Photo Album App Guide (Real World Example)http://anonsvn.jboss.org/repos/richfaces/branches/community/3.3.X/docs/photo_album_app_guide/http://docs.jboss.org/richfaces/latest_3_3_X/en/realworld/
    User Guidehttp://anonsvn.jboss.org/repos/richfaces/branches/community/3.3.X/docs/userguide/http://docs.jboss.org/richfaces/latest_3_3_X/en/devguide/

    Deliverables

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

    New BookIncorporating some elements fromComments
    Migrating to RichFaces 4.0Migration Guide
    Developer GuideUser Guide
    Component ReferenceUser Guide
    Component Development Kit GuideComponent Developer Kit Guide
    Photo Album Demonstration GuidePhoto Album App GuideDetermined to not be required
    FAQ and TroubleshootingFAQWiki and forums determined to be more suitable

    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

    PhaseDeliverablesTasksDue Date
    Phase One: Information Planning (10%)Friday, 4 September 2009
    Information PlanFriday, 4 September 2009
    Initial Project PlanFriday, 4 September 2009
    Phase Two: Content Specification (20%)Wednesday, 14 October 2009
    Content SpecificationWednesday, 14 October 2009
    Revised Project PlanWednesday, 14 October 2009
    Phase Three: Implementation (50%)Wednesday, 31 March 2010
    Formal First DraftsMigration Guide

    Wednesday, 25 November 2009

    Component ReferenceWednesday, 27 January 2010
    Developer GuideFriday, 19 February 2010
    Component Development Kit GuideWednesday, 3 March 2010
    Tech ReviewsMigration GuideTBA

    Component ReferenceMonday, 1 February 2009
    Developer GuideWednesday, 24 February 2010
    Component Development Kit GuideMonday, 8 March 2010
    Re-draftsComponent ReferenceMonday, 8 March 2010
    Developer GuideWednesday, 24 February 2010
    Component Development Kit GuideMonday, 8 March 2010
    Migration GuideWednesday, 17 March 2010
    Final DraftsComponent ReferenceMonday, 22 March 2010
    Developer GuideThursday, 25 March 2010
    Component Development Kit GuideMonday, 29 March 2010
    Migration GuideWednesday, 31 March 2010
    Phase Four: Production (19%)Friday, 14 May 2010
    TranslationFriday, 14 May 2010
    Phase Five: Evaluation (1%)Tuesday, 18 May, 2010
    Maintenance (Bugzilla)Tuesday, 18 May 2010
    EvaluationTuesday, 18 May 2010

    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.