Making GNOME documentation suitable for different distros.

[Pat Costello <Patrick Costello Sun COM>]

Hi Everyone, 

The documentation team in Sun have recently been giving some thought to the question of how to deal with variations across different distributions of the GNOME Desktop. Although we have
aimed to produce a vanilla variety of Help manuals and documentation up to now, this approach is becoming increasingly less practicable. Ideally, we need an approach that satisfies the standard GNOME Desktop requirement, and is also suitable for use by the various distros such as Redhat, Sun and Ximian.

Furthermore, if we can make the Help and documentation broadly applicable, then we remove a potential stumbling block for other parties interested in distributing the GNOME Desktop. So, the question is, how best can we structure Help and documentation to be suitable for all distros? 

Different distros usually have different menu paths to launch applications. These differences are not always modified in the documentation, so the Help is inaccurate or misleading for users in some distros. The way we are planning to handle this scenario for the manuals that the Sun team is looking after, is by putting all menu path information in one place only. That way, the information can be easily updated for use by different distros. In other words, you only need to update one Help
document, rather than dozens, if you want to make menu changes in your distro. The place where we will put the menu path information is in the GNOME Desktop User Guide, in a new section. We will replace the menu path information in the individual Help manuals with a reference to the User Guide.

There are other variations in distros that cannot be resolved by the above strategy. To cater for those variations in the next Sun distribution of the GNOME Desktop, we are creating a Quick Start User Guide that documents characteristics that are specific to the Sun distribution. The GNOME Desktop User Guide will still document the standard Desktop. Although the Quick Start User Guide that we are creating contains some Sun-specific information, we will put the manual back into the
GNOME community as an example that other people can use to create their own distros. 

This approach will go some way to making documentation more suitable for all distros, and will thus benefit end-users. If the approach works in practice, we can introduce refinements in the light of future experience.

Pat