CMS Software Documentation Policy

Complete:

Introduction

This document defines the different actors and their responsibilities in the CMS Software Documentation and its maintenance.

CMSSW documentation suite

The CMSSW documentation consists of three main elements:

• the CMS Offline WorkBook
• the CMS Offline SW Guide and
• the CMSSW Reference Manual.

The WorkBook contains the instructions on accessing computing resources and using the software to perform analysis within the CMS collaboration.

The Offline SW Guide gives full details of CMS Software including description of algorithms and software architecture, instructions for analysis and validation and common items such as developers’ guide, trouble shooting guide, FAQ lists, and instructions for code optimization.

The Reference Manual contains the release dependent technical documentation such as class lists, brief description of content and purpose of each package and default configuration files and sequences.

Structure

The general structure of the WorkBook, the Offline SW Guide and the Reference Manual is defined and maintained by the respective editors taking into account the input from the end-users and from the management.

The WorkBook and the Offline Guide are structured twiki documents and the pages belonging to them start with the strings “WorkBook” and “SWGuide”, respectively.

The Reference Manual is a doxygen generated document which picks up the contents from the files in the CMSSW cvs directory.

There should be no other web pages containing instructions on CMSSW or its usage than those in these three documents. Cross-linking between these documents is encouraged; there should be no duplication of the information. The responsibilities of different actors are described in the following for each of these documents.

WorkBook

Each WorkBook page has a responsible person who is expected to keep the page updated such that correct information and instructions are always provided. S/he adds new page according to contributor guidelines (contained in the WorkBook), adds content, and in the case of a tutorial, verifies that the instructions work and checks his/her tutorial pages whenever a new CMSSW release has come out, and on "as needed" basis.

Once a year, WorkBook goes through a major review organized by the editors to verify that contents are useful and correct, and that the topics are properly covered. On this occasion, the responsible person checks the page which is then reviewed by the persons in charge of services described in the page, or leaders of the different activities in computing, software or physics areas covered by the subject. The review is scheduled so that the WorkBook review is the task of the new conveners of each group in the beginning of the year, wherever applicable.

Offline Guide

The Offline SW Guide is structured into domains which most often coincide with the organization of the Offline and Computing and Physics Projects. Each subgroup in these projects nominates a contact person for documentation and user support issues. These contact persons are responsible of the contents in the Offline SW Guide and they organize the documentation work within the group with technical help of the User Support. They also help identifying experts in the group in case of user questions on areas under the group’s responsibility.

For readability of the document, the main pages for each domain have a similar structure - a template page is provided. For each domain, the main page should include links to the existing documentation in the WorkBook. All relevant instructions for the use of the code should be provided, and all algorithms used in the domain should be documented, in case of an existing written note, a link to the note is sufficient.

Reference Manual

Package administrators are responsible for providing the basic description of the purpose and the contents of each package in the Subsystem/Package/doc/Package.doc file. The instructions on how to generate this file are linked from the main page of the Reference Manual. The existence of this file will be checked before each major release, and the package will not be integrated into the release unless the description file is provided.

The class header files should be properly documented so that the class and all its (non self-explanatory) public members have a brief description appearing in the class list.

The Reference Manual should contain Release Notes for each major release; they are compiled by the release integrators of the subsystem and contain information on the major changes and new features affecting the users of the subsystem.

Sources

http://indico.cern.ch/conferenceDisplay.py?confId=22389

Review status

Reviewer/Editor and Date (copy from screen)	Comments
KatiLassilaPerini - 22 Nov 2007	created the page

Responsible: KatiLassilaPerini
Last reviewed by: Most recent reviewer