Installation guide: notes on design for re-usability

StartInstall is a starting point for various step-by-step installation guides. The System.InstallationGuide, covering generic Unix on Apache installs, is broken up into different steps; the initial starting point is InstallOverview. In order to allow a new guide to pick up all of the steps from the generic guide and just override specific pages where a special step needs to be done, the generic guide is designed to be reused. CreateInstallGuide contains instructions on how to create a new customized installation guide.

In order to support customization, each step in the generic guide does not link directly to any of the other steps. Instead, it INCLUDEs a helper topic to generate links, passing the name of the generic step and a variant suffix. Each customized installation guide has a unique variant suffix; the generic guide has no suffix. The helper topic checks to see if a topic exists in the form of <GenericStep><VariantSuffix>; if it does, then the topic outputs a link to this customized page. Otherwise, the topic outputs a link to the generic page. Therefore by setting the variant suffix as a macro on the initial overview topic, and in any topics for customized install steps, any generic pages referred to by the customized installation guide will automatically pick up any customized pages.

For example, InstallOverviewSolaris10 is a customized version of InstallOverview, where the variant suffix is Solaris10. InstallOverviewSolaris10 simply INCLUDEs InstallOverview, passing in the Solaris10 variant suffix:

%INCLUDE{"InstallOverview" IGVariant="Solaris10"}%

As InstallOverview uses the helper topic GetInstallStep to generate its links, it will automatically link to the Solaris10 variants of the install steps if they exist; otherwise, the generic topic without any suffix will be linked. Here is what InstallOverviewSolaris10 looks like after GetInstallStep returns its output:

---+ Installing Foswiki: Overview

   * [[/Support/InstallStepSystemRequirementsSolaris10][Verify system requirements]]
   * [[/Support/InstallStepDownloadUnpackSolaris10][Download and unpack the Foswiki distribution]]
   * [[/Support/InstallStepSetPermissionsSolaris10][Set the file and directory permissions for the installation]]
   * [[/Support/InstallStepConfigureExecPathsSolaris10][Configure the locations of the Perl executable and the Foswiki modules]]
   * [[/Support/InstallStepConfigureWebServerSolaris10][Configure the web server]]
   * [[/Support/InstallStepConfigureFoswikiSolaris10][Configure Foswiki]]
   * [[/Support/InstallStepEnableAuthentication?IGVariant=Solaris10][Enable authentication of users (if desired)]]
   * [[/Support/InstallStepDefineAdminUsers?IGVariant=Solaris10][Define the administrator users]]



   * [[/Support/InstallStepAdvancedConfig?IGVariant=Solaris10][Perform more advanced configuration]]


Next step: [[/Support/InstallStepSystemRequirementsSolaris10][Verify system requirements]]
Up: [[/Support/%IGStepUp%?IGVariant=Solaris10][%IGStepUpText%]]

Note links to the generic topic also set the IGVariant parameter, so that the destination topic will in turn pass on the variant information when it INCLUDEs GetInstallStep.

To generate the navigation links, the helper topic ShowInstallStepNavigation is used. ShowInstallStepNavigation accepts parameters for the next install step, previous install step, and parent install step, as well as the link text to display for the links. For example, the InstallStepSetPermissions topic has the following text to show its navigation:

%INCLUDE{"ShowInstallStepNavigation" IGStepUp="InstallOverview" IGStepUpText="Overview" IGStepPrevious="InstallStepDownloadUnpack" IGStepPreviousText="Download and unpack the Foswiki distribution" IGStepNext="InstallStepConfigureExecPaths" IGStepNextText="Configure the locations of the Perl executable and the Foswiki modules"}%

When creating a customized install step, or if you write a new install step designed to be reused by multiple installation guides, then you must use the GetInstallStep helper topic to generate any links to other steps. You should use the ShowInstallStepNavigation helper topic to display the navigation links.