next up previous
Next: Routines/Code Documentation Up: Infrastructure Software Previous: Calibration Management

Software Documentation

Good documentation will be a key to smooth and efficient operation of the subsystem. For a distributed group, like the STAR On-Line containing many subgroups such as the SVT, the organization of a good information system is essential.

Requirement:

The subsystem development has to be well documented.

Justification:

Good documentation of the system development allows new members to join and continue the work started by others so there is no need to regenrate from scratch parts of the system in case the author leaves the collaboration.

Status:

Under discussion.

Requirement:

The hard implementation should be documented in details in connection with the software system.

Justification:

It is essential to know what the hardware is to understand what the software should do.

Status:

Under discussion.

Requirement:

There should be ``in-line'' documentation of the code.

Justification:

Allows to know what specific parts of code are doing.

Status:

Under discussion.

Requirement:

There should be documentation on all routines by specification of a synopsis, a long description, a list of inputs and output variables (implicit and/or explicit), a list of possible return values, and a list of side effects.

Justification:

These information are meant to allow the software developer to consider the routines as black boxes with well defined inside/outside boundaries.

Status:

Under discussion.

Requirement:

Notes that clearly explain the design, describe the algorithms that are used and explain the implementation must be provided.

Justification:

Justification of requirement

Status:

Under discussion.

Requirement:

User's guide for the On-Line subsystem will be generated.

Justification:

Justification of requirement

Requirement:

All the documentation should be generated along with the Control System Software.

Justification:

Justification of requirement

Status:

Under discussion.

Requirement:

All the documentation must be readily available so that it can be found when needed.

Justification:

Justification of the requirement

Status:

Under discussion.

Requirement:

There should be a User Guide that describe the different components of the monitoring program.

Justification:

Justification of the requirement

Requirement:

There should be On-Line help on the various commands and parameters monitored by the subsystem.

Use STAR code management system. Develop a protocol by which all svt code gets review and documented by group.





next up previous
Next: Routines/Code Documentation Up: Infrastructure Software Previous: Calibration Management



Claude Andre Pruneau
Thu Oct 12 18:10:03 EDT 1995