EMI Documentation Guidelines

This page contains a set of guidelines to produce the documents that Product Teams should produce in EMI.

Introduction

The minimum documentation requirements as reported in the SQAP includes:

• Software Requirements Specifications
• Software Design Description
• Software Verification and Validation Plan
• Software Verification and Validation Report
• User Documentation
• Installation Guide
• Troubleshooting Guide

Documents

Software Requirements Specifications

Description: The Software Requirements Specifications should define the requirements of the software component.

Author: PTB

Requirements: The PTB will decide whether a detailed document describing the software requirements is needed or not. Otherwise a tracking tool will be used to describe and track the requirements. Validation criteria (which tests are needed to verify the requirements) should be also included.

Software Design Description

Description: The Software Design Description should describe the software architecture of the software component.

Author: PTB or a delegated person by the PTB.

Requirements: The PTB will decide whether a detailed document describing the software design is needed or not per software component basis.

Software Verification and Validation Plan

This document describes the testing strategy for a given software component. The Certification&Testing guidelines provide a template that lists the topics this document should address: Template

The same twiki contains also a template for the Software Verification and Validation report: Report Template

User Documentation

Description: The User Documentation should contain all the necessary information needed by the users of the software.

Author: Product teams.

Requirements: The User documentation for each EMI software component should contain when applicable:

• Introduction to the software component describing the main functionality and architecture.
• Installation and configuration instructions.
• Access or log-on and sign-off the software.
• Information on software commands: required parameters, optional parameters, default options, order of commands, and syntax.
• Description of all error situations which can occur and how to react.
• Glossary with terms specific to the usage of the software component.
• References to all documents or manuals intended for use by the users.
  • Known Issues
  • System Administrator Guide (if any)
  • Tutorials *Developer‟s Guide i.e. API documentation, Build instructions.

Installation Guide

Description: The Installation Guide should contain the necessary instructions on how to install and configure the software.

Author: Product teams

Requirements: The Installation Guide for each EMI software component should contain:

• The list of supported platforms
• Software and Hardware requirements to install the software component
• Installation instructions
  • Supported installation tools
  • Installation command
• Configuration instructions
  • Default configuration variables
  • Mandatory configuration variables
  • Configuration command
• Known Issues during Installation and Configuration of the software component.

Troubleshooting guide

Description: The Troubleshooting Guide of each EMI software component should help users when tracking and solving problems.

Author: Product teams

Requirements: The Troubleshooting Guide for each EMI software component should describe the most common scenarios where users have problems in the following areas:

• Installation
• Configuration
• Administration
• Debugging

Contacts

EMI SA2

References

* DSA2.1 – SOFTWARE QUALITY ASSURANCE PLAN EU DELIVERABLE: DSA2.1

Logbook

• Mon Jan 24: first draft based on DSA2.1

-- GianniPucciani - 24-Jan-2011