| <h1>v3 Distributions Documentation</h1> The delivery of GlassFish v3 in multiple distributions raises the question of whether the unbundled documentation, namely manuals that are published on the docs.sun.com(SM) site, should also be delivered in multiple documentation sets. The chosen solution will apply only to unbundled documentation. The question of whether bundled documentation, such as online help and man pages, will be delivered as modules with their respective distributions, will be determined by whether the documentation can be merged at installation time or runtime.
Note - Irrespective of the solution chosen, each topic that does not apply to all installations must be labeled as such. Many users are likely to reach such topics through search, so we cannot rely exclusively on separation to indicate that some topics do not apply to the distribution for the web profile.
Decision: All distributions in one document set with all topics on a subject in one document Advantages:
- Information for all users is available in one place.
- Users who have an installation that is part way between distributions know where to look for documentation.
- Users upgrading from GFv2 will find that their new doc set is similar to their old one.
- Features available with an upgrade or from the update center are advertised.
- Providing a Documentation Center for each distribution can help with navigation.
Disadvantages:
- Delivery of IPS packages tailored for a distribution is not possible.
- Users whose installations do not include all components might erroneously assume that the entire documentation set applies to their installations.
Other Options Considered One documentation set per distribution This solution is similar to the provision of separate documentation sets for the platform and enterprise editions of earlier Application Server releases. Advantages:
- Users of a particular distribution can be provided only with information that is relevant to them.
- Delivery of IPS packages that are tailored for a specific distribution is possible.
Disadvantages:
- Users whose installation is in some kind of intermediate state, halfway between distributions, might not immediately know where to find documentation for their installation.
- Users who have witnessed in earlier release the replacement of multiple documentation sets for multiple editions with a single documentation set might be confused by the reappearance of multiple documentation sets.
- No advertising of features available with an upgrade or from the update center.
Incremental documents in the same documentation set All distributions in one document set with incremental documents for topics that apply to the more fully featured distributions, for example, one Administration Guide for the Web distribution and one for the Classic distribution Advantages:
- Risk of misleading users whose installations do not include all components is reduced.
- Information for all users is available in one place.
- Features available with an upgrade or from the update center are advertised.
- Providing a Documentation Center for each distribution can help with navigation.
- Delivery of IPS packages tailored for a distribution is possible.
Disadvantages:
- Does not scale.
- The larger size of the documentation set, with two or more "levels" of many of the books, might overwhelm or confuse users.
- Users whose installation is in some kind of intermediate state, halfway between distributions, might not immediately know whether a given feature is in the docs for the Web or Classic distribution, even if the docs are in the same set.
|
