Documentation for myGrid Components

This page describes the minimal documentation requirements for each myGrid component.

Documentation file organization

Documentation for each component will mainly be contained inside a doc directory within the top-level directory of the component, with two standard document files in the top-level directory itself. The minimal documentation requirements are as follows:

    <component>
      |   LICENSE.TXT
      |   README.TXT
      |
      +-- doc
             INSTALLATION.TXT
             RELEASE-NOTES.TXT
             USERGUIDE.DOC

Minimal documentation set

LICENSE.TXT

The standard Lesser General Public License (LGPL) v2.1: see LicensingStuff

README.TXT

A short document identifying the component and its purpose, and identifying the other documentation files for the component. See example

NSTALLATION.TXT

A step-by-step guide to installing and configure the component from the suppplied files. See below for guidance on the contents of the file; see example

RELEASE-NOTES.TXT

A document outlining the change history of the component between releases and any known issues (i.e. problems or limitations). See example

USERGUIDE.DOC

A longer document describing the purpose, structure and use of the component. See below for guidance on the contents of the file. Optionally, the contents over the document can be divided into several files. The suggested format for this documentation is Microsoft Word, which can also be read and written by OpenOffice

Guidance on document contents

INSTALLATION.TXT

The installation note should provide clear and unambiguous notes on installing and deploying the component.

It should identify the contents of the download archive, describing (in general terms) the contents of each directory.

It should clearly identify the environment for deploying and using the component, in terms of expected software, its parent website and its release identification. For example:

• Ant
• Java JDK/JRE
• Tomcat
• MySQL
• Taverna
• Freefluo
• Other myGrid components

It should describe basic configuration options, but may refer to the user guide (or other supporting documentation) for advanced configuration options.

Note that the first release of myGrid components, from which the example is taken, was in source form only. For the current and subsequent releases, we should aim to deploy from pre-built, binary, download archives. The installation note should reflect this, with source archive layout and build process contained in an appendix.

USERGUIDE.DOC

The structure of the user guide (whether supplied as a single document or several) will vary according to the nature and purpose of the component.

In each case, the user guide should describe the purpose and function of the component within myGrid.

If the component has a direct user inerface (either command line or graphical) then the user guide should describe commands, options, menus, and/or drag-and-drop features etc.

If the component has a web service interface, the user guide should identify the operations and parameters, typically by reference to a WSDL description and any supporting XML schemas.

Other documentation

Where it exists, the component should include documentation relevant to developers (e.g. design, test procedures).

-- NickSharman - 11 Oct 2004