EMI Documentation Guidelines

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


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


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






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

-- GianniPucciani - 24-Jan-2011

Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r2 - 2011-01-24 - GianniPucciani
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Main All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback