EMI Documentation Policy

1. Introduction

The Documentation Policy defines which software documents must be provided for EMI software products.

This policy doesn't describe Test plans or Test reports since they are covered in detail by the Testing Policy [R1].

2. Documentation Review Process

The Documentation Review process is described in detail in R2. The Documentation Team is responsible for the Documentation Review Process. The Documentation Team is coordinated by the SA2.5 task and is comprised of members from NA2 and SA2 activities.

3. Documentation Accessibility

EMI documentation must be accessible from the EMI public web site [R3]. NA2 is responsible for maintaining the documentation information in the EMI public web site.

4. Documentation Changes

Documentation is expected to be valid for an EMI major release [R7]. However updates may be needed for several reasons:

• A user requests a clarification or reports missing or inaccurate information in the documentation.
• A change in the software that also requires an update in the documentation because it implies new functionality, new CLI option, etc.

PTs are therefore responsible for keeping documentation up to date. If a documentation change is done at the same time a new product version is going to be released, then the associated release notes should also contain a reference to the documentation changes. For more details, please check section 8.1.1. If documentation changes occur without a new associated product version, the PT should contact the Documentation Team. For more details, please check the Documentation Review process [R2].

5. Documentation Versioning

Documentation must be properly versioned. For example, a possible schema version could be X.Y where:

• Y is increased every time there is a major change.
• Z is increased every time there is a minor change.

A change log must be included in the document to track the changes from one version of the document to another.

6. Documentation Format

The preferred format fot EMI technical documentation is PDF, when this is applicable for the type of document. See specific details for each document in section 8.

Documents can be grouped together (i.e. Users Guide and Developers Guide under the same guide) or can be kept under separate files. It's up to the PTs to decide how to organise the documentation. If several documents are grouped together, the corresponding sections must be easy to identify with the document they describe according to this policy (i.e. If Users Guide and Developers Guide are grouped together under the same guide, there should be a section clearly identifying the Users Guide part and the Developers Guide part so that users can easily find the information they are looking for).

The following elements must be present in the cover page for the applicable documents distributed in PDF:

• EMI logo
• Document title: it includes the document type and the EMI product name [R8]. i.e. DPM User guide, UNICORE Registry Administrator Guide or ARC CE Service Reference Card.
• Document Version: See section on Document Versioning for more details.
• EMI Product Version: Version of the EMI Product [R7] for which the documentation applies. It can be expressed for a set of versions i.e. 1.X or 1.7.X.
• Date: date when the document is last reviewed (read and approved) by the PT.
• EMI funding acknowledgement:

  This work is co-funded by the European Commission as part of the 
  EMI project under Grant Agreement INFSO-RI-261611.
  

A DOC, TEX, PDF template [R4] for the cover page is provided as an example. Please, adapt the provided template to your document style and format.

7. Intended Audience

The following audiences have been identified for EMI software documentation:

• Users: they are grid users managing jobs, data, and retrieving information about resources. They use EMI software products. They can be advanced or novice users. This means documentation has to be useful for novices as well, so prior knowledge on grid technologies can't be taken for granted when preparing the documentation.
• System Administrators: they are responsible for installing, configuring and running EMI software products so that thay can be used by users. They are experts in software but not always experts in the grid. Therefore, documentation must be written setting the context and making everything clear so that non grid experts can also find it useful.
• Developers: they are expert software users interested in technical aspects of the software. Documentation covering technical areas like API descriptions, return and error codes, DB schemas, etc has to be also available.

Documentation should be also associated to the product type. Four main product types have been identified according to [R8]:

8. Documentation

8.1. General Documentation

8.1.1. Release Notes

Release Criteria: Mandatory for all products.

Additional Format requirements: Release notes must be provided in the release task associated to the product. The PDF document is not needed in this case.

Description: They are a non-technical text written in good english giving an overview of the change introduced by the packages. It should contain the following structure:

• What's new: brief description of the main changes, both new features and bug fixes, and also documentation changes.
• Installation and configuration: more details on installation and configuration stating very clearly if the service must be reconfigured and/or restarted.
• Known issues: List of known issues with reference to the corresponding GGUS ticket or RfC tracking the issue and their known workarounds.

In case the updated product contains the fix for a security vulnerability the Release Notes/What's New section must also contain the reference to the EGI SVG: Advisory. No other details disclosing information about the vulnerability should be made.

8.1.2. Functional Description

Release Criteria: Mandatory for all products.

Description: Introduction to the software product describing the main functionality and its architecture. This document needs to be updated when new functionality is introduced in the product.

8.1.3. Software Requirement Specification

Release Criteria: Optional. Applicable to all products.

Description: The Software Requirement Specification is a document that describes the requirements of the product. It's a complete description of the behaviour of the system to be developed. It includes the interactions the users will have with the software and it also contains non-functional requirements which impose constraints on the design or implementation.

8.1.4. Software Design Description

Release Criteria: Optional for existing products, mandatory for all new products.

Description: The Software Design Description is a document that describes the software architecture of the product.

8.2. User Documentation

8.2.1. User Guide

Release Criteria: Mandatory for product type client and service and clients.

Description: The user guide must contain all the necessary information needed by the users to know how to use the software product. A user guide answers the question How do I...?

8.2.2. Client Installation and Configuration

Release Criteria: Mandatory for product type client and service and clients.

Description: The client installation and configuration document contains the necessary instructions on how to install and configure the software product clients. It must contain at least:

• Installation instructions:
  • Supported installation tools (i.e. YUM for SL platforms).
  • Installation command (i.e. yum install sherpa-client).
• Configuration instructions:
  • Default configuration variables.
  • Mandatory configuration variables.
  • Configuration command. (the command, if any, that the system administrator has to run in order to configure the client).

Note that this information may be gathered for all clients under the emi-UI/emi-WN umbrella.

8.2.3. Client Configuration Template

Release Criteria: Optional. Applicable to product type client and service and clients.

Additional Format requirements: The PDF document is not needed in this case. It's up to the PTs how they want to distribute the template.

Description: The client configuration template defines the complete list of configuration variables that need to be defined by the user to configure the client. It has to clearly indicate:

• mandatory and optional variables
• default values if applicable
• clear examples for those variables that need to be defined by the user.

8.2.4. Man Pages/Online Help

Release Criteria: Optional. Applicable to product type client and service and clients

Additional Format requirements: The PDF document is not needed in this case.

Description: Man pages or online help containing a detailed description of the available commands to use the software product must be provided. They should include:

• command syntax
• required parameters with default options
• optional parameters with default options

8.2.5. Client troubleshooting Guide

Release Criteria: Optional. Applicable to product type client and service and clients.

Description: Guide describing anomalous situations that can occur while using the clients (CLI, web UI, etc) and how to react. It can include:

• • Error message descriptions.
  • Advice on how to avoid some common errors.

8.3. Developers Documentation

8.3.1. API Documentation

Release Criteria: Optional. Applicable to product type libraries/utilities, service and service and clients.

Description: API documentation contains the description of functions, objects, classes, etc that are available in a library allowing developers to interact with the software product.

8.3.2. Service Interface description

Release Criteria: Optional. Applicable to product type libraries/utilities, service and service and clients.

Description: EMI services should come with documented interfaces. The service interface documentation can reference existing standards in case the service interface is standard-based.

8.3.3. Build Documentation

Release Criteria: Optional. Applicable to product type libraries/utilities, service and service and clients.

Description: Build documentation contains the set of intructions needed to build the software product. It must include:

• basic compiler and library requirements, if any
• build procedure

8.3.4. Error Code Documentation

Release Criteria: Optional. Applicable to product type libraries/utilities, service and service and clients.

Description: The error code documentation contains a list of messages that correspond to faults in the software product.

8.4. System Administrator Documentation

8.4.1. System Administrator Guide

Release Criteria: Mandatory for all product types (except client and libraries/utilities products that are always included as part of other products).

Description: The System Administrator guide contains the necessary instructions on how to install and configure the software product. When the software product is a service, it also includes instructions on how to run and maintain the service. The TOC for the system administrator guide for each EMI software product must contain, at least:

• Introduction: Short description for system administrators
• Quickstart guide: List of commands to setup a minimal working installation and check that everything installs correctly
• Prerequisites and Recommendations
  • Hardware: Specified independently for each platform if there is any difference
    • CPU
    • Memory
    • Disk
    • Network
    • Other requirements
  • Virtualized environments: If needed, you can provide recommendations for virtualized environments
  • Software: Only what it's not installed by the metapackage. Specified independently for each platform if there is any difference.
    • Operating system
      • OS version(s)
      • OS configuration: All sections only if applicable
        • File systems: Requirements or recommendations the partitions, size, etc
        • Time synchronization: At least, if it's required or not, more details if needed
        • Host certificates: At least, if it's required or not, more details if needed
        • Networking
          • Open ports: A link to the service reference card
          • TCP/IP stack configuration: Recommendations to optimize the TCP/IP stack. Specify if it's done automatically or not
        • Kernel configuration:
          • SElinux
      • Other
    • Pre-installed software: Prerequisites for other software, if not covered by metapackage installation
    • Recommended deployment scenarios: Provide a brief description of the recommended deployment scenarios. Every deployment scenario should specify with which other services interact and all the information of the remote services needed to configure it properly
    • Other requirements
• Installation
  • Software repositories: Any special requirements on repositories besides generic
  • Clean installation: The procedure to install from scratch
  • Upgrade: The procedure to upgrade, and it should specify from which versions is possible to upgrade
• Configuration
  • For each scenario you should provide a minimum configuration (for example the minimum YAIM configuration to make it work)
  • Configuration parameters: The name, the values, a description of the parameter (it can be a link to a place where this is already described)
• Interaction with other products: For each deployment scenario, if there is an integration guide, a link should be provided, otherwise this information should be provided here
• Service operation: All sections only if applicable
  • Service validation / monitoring
    • Basic tests: To check that installation and the configuration were fine
    • Monitoring availability: Are there NAGIOS Probes and what do they cover / not cover
  • Typical operation / maintenance scenarios
    • Expanding / scaling the service to a larger size
    • Periodic maintenance
    • Service migration
  • Service performance
    • Testing / monitoring: Instructions or a link to a tool / script
    • Optimization recommendations
• Troubleshooting: At least, a link to an updated list of known issues and workarounds for the considered version

8.4.2. Configuration Template

Release Criteria: Optional. Applicable to all products types (except client and libraries/utilities products that are always included as part of other products).

Additional Format requirements: The PDF document is not needed in this case. It's up to the PTs how they want to distribute the template.

Description: The service configuration template defines the complete list of configuration variables that need to be defined by the system administrator to configure the service. It has to clearly indicate:

• mandatory and optional variables
• default values if applicable
• clear examples for those variables that need to be defined by the user.

8.4.3. Service Reference Card

Release Criteria: Mandatory for product type library/utility, service and service and clients.

Additional Format requirements: A twiki page linked from the EMI EMT twiki page [R5] is also mandatory together with the PDF file.

Description: The service reference card is a reference manual for advance system administrators summarising service related information needed to operate and maintain the service. The service reference card must contain:

• • Daemons running in the service.
  • Init scripts and how to use them.
  • Location and description of configuration files.
  • Location and description of log files.
  • Open ports.
  • Description of existing cron jobs.
  • Description of existing utility scripts.
  • Security related information:
    • Access control mechanism description (authentication & authorization).
    • How to block/ban a user.
    • Network Usage.
    • Firewall configuration.
    • Security recommendations.
    • Security incompatibilities.
    • List of externals packages that are not maintained by the supported OS.

A template for the Service Reference Card can be found in this R6.

8.4.4. Troubleshooting Guide

Release Criteria: Optional. Applicable to all products.

Description: Guide describing anomalous situations that can occur while installing, configuring or running the service and how to react. It can include:

• Error message descriptions.
• Advice on how to avoid some common errors.

9. Contacts

10. Table of References

Reference	URL
R1	EMI Testing Policy https://twiki.cern.ch/twiki/bin/view/EMI/EmiSa2TestPolicy
R2	EMI Documentation Review Process https://twiki.cern.ch/twiki/bin/view/EMI/EMIDocReviewProcess
R3	EMI Documentation in the public web site http://www.eu-emi.eu/documentation
R4	EMI Technical Documentation Cover Page Tamplate https://twiki.cern.ch/twiki/pub/EMI/EmiTemplates/emi-tex_pdf_templ.tar.gz
R5	EMI Service Reference card list https://twiki.cern.ch/twiki/bin/view/EMI/EMTSrcTemplate#SrcLinks
R6	EMI Service Reference card template https://twiki.cern.ch/twiki/bin/view/EMI/EMTSrcTemplate#SrcTemplate
R7	Change Management Policy https://twiki.cern.ch/twiki/bin/view/EMI/EmiSa2ChangePolicy
R8	EMI Technical Development Plan https://twiki.cern.ch/twiki/pub/EMI/DeliverableDNA132

11. Logbook

Details Hide Details