FishCAT Documentation Reviews

Documentation reviews are an important part of FishCAT. By reviewing documentation you directly improve the quality of GlassFish and greatly benefit GlassFish users and developers.

This page provides important details about performing FishCAT doc reviews for the GlassFish v3 release. Please read this information before starting your reviews.

Review Priorities
Review Drafts
Review Guidelines
Review Points
Review Questions
Questions about FishCAT for GlassFish v3? See the main FishCAT page or contact the [quality mailing list].

Review Priorities

The following GlassFish v3 documents have priority for review. Please review these first.

• Administration Guide
• Quick Start Guide
• Application Development Guide (formerly Developer's Guide)
• Application Deployment Guide

Review Drafts

Which draft should be reviewed? Please follow these important guidelines.

• For documentation bundled with the product (CLI man pages, Admin Console GUI online help, HTML pages such as the Quick Start Guide, etc.), review the bundled documentation in the GlassFish v3 build that you are testing. Note the following:
  • The latest Admin Console GUI online help is available from build 71 onward.
  • The latest man pages are available from build 69 onward, and in the Reference Manual.
  • Bugs filed against the bundled docs by October 30, 2009 will be fixed for the GlassFish v3 release. This deadline enables issues to be fixed for hard code freeze.
  • Bugs filed against the bundled docs after October 30, 2009 will not be fixed for GlassFish v3 unless they are deemed to be showstoppers. These issues will be fixed post-GlassFish v3.

• For documentation not bundled with the product (Administration Guide, Application Development Guide, and so on), review the GlassFish v3 docs listed as Ready for Review on the documentation comments wiki. Click the link for a specific doc under Ready for Review and then follow the instructions on the corresponding comment page. Review drafts are available in PDF format. Please also see Review Priorities.

If you have any questions about which drafts to review and how to access them, contact the [quality mailing list].

Review Guidelines

Administration Console online help (bundled)

• A review of 10 task pages and 5 reference pages counts as a documentation review.
• Review all information and perform any procedures within the task pages.
• If possible, cross-check the help against the GUI.
• Provide detailed information about issues in the help, such as why an explanation is unclear. Also provide missing information, such as why users should set a particular option.
• File issues in Issue Tracker, including contact e-mail information so writers can follow up as necessary. Please also use [FishCAT] somewhere in the bug report to assist with identification.
• Send e-mail to the [quality mailing list], indicating which pages have been reviewed.

Note: To access the Admin Console GUI online help after installation, click Help in any GUI screen.
\

CLI man pages (bundled)

• A review of 15 pages counts as a documentation review.
• Review all information, try asadmin with each command, check everything on the page (including option descriptions), and perform and verify the correctness of any examples.
• File issues in Issue Tracker, including contact e-mail information so writers can follow up as necessary. Please also use [FishCAT] somewhere in the bug report to assist with identification.
• Send email to the [quality mailing list], indicating which pages have been reviewed.

Note: To access the CLI man pages after installation, execute the following command:

as-install/bin/asadmin asadmin-subcommand--help|more

For example:

as-install/bin/asadmin start-domain --help|more
\

Guides and tutorials (unbundled)

• A review of 100 pages (or a complete document if it is less than 100 pages) counts as a documentation review.
• Review all information and perform any procedures within the 100 pages.
• Record issues for a specific document on the document's comment wiki page. Be sure to include [FishCAT] with your comment ID. For example, [FishCAT] jsmith-01. If you prefer, you can also file issues in Issue Tracker. Please also use FishCAT somewhere in the bug report to assist with identification.
• Send email to the [quality mailing list], indicating which pages have been reviewed.

Note: To access the unbundled docs that are ready for review, go to the documentation comments wiki and click the link for a document listed as Ready for Review. Please also see Review Priorities.

Review Points

Doc review points will be tallied as follows.

In cases where it is not clear from the bug report or comment page how much of a doc was reviewed, assessments will be made and points awarded accordingly.
\

Review Questions

If you have any questions about FishCAT documentation reviews, please raise them on the [quality mailing list]. We're standing by to help.

And thanks for your reviews!

Amazing work was done by FishCATs for the GlassFish v3 Prelude and GlassFish v3 releases (also see the survey results). We appreciate your contributions, which directly improved the quality of GlassFish v3 documentation, and look forward to working with you in the future.
\

Main FishCAT page