4 Document Guidelines

The purpose of these document guidelines is to create a coherent set of documents that clarify the goals of the various software development teams and the functionality of the software they create. These documents are meant to be readily available not only to the development team members, but also to management and other interested parties.

The creation of these documents is closely related to the software life cycle described in Section 3. For example, the existence of a reviewed requirements document demonstrates that the requirements definition phase of a project has been completed.

Section 4.2 provides specific guidelines for each of the documents, suggests responsibility for their creation and maintenance, and describes how the documents are interrelated.

4.1 General Guidelines

4.1.1 Accessibility

Documents developed for the CCSM will be organized and made available for browsing and downloading via the Models and Documentation subsection of the CCSM web site. Eventually they will also be made available to developers through the CCSM repository.

4.1.2 File format

Documents should be available in both web-browsable (e.g. html) and print-friendly formats. We recommend that they be written in LaTeX and based on a set of templates (see section 4.2). LaTeX was chosen because:

it is a format that many people are already familiar with;
it can produce both print and web documentation by using text-to-html tools such as latex2html;
it is the format generated by the F90/C++ compatible auto-documentation tool ProTeX.

4.2 Development Documents and User Documentation

Below are descriptions of the recommended development documents with guidelines on content. Templates for the documents are available at:

ftp://ftp.cgd.ucar.edu/pub/ccsm/dev_guide/software_docs.tar.gz

Using a consistent format will make it easier to compile the documents and maintain them as a coherent body of documentation.

4.2.1 Requirements Document

Purpose Establishes the functionality required.

Contents Scientific and computational requirements.

Notes Component and module requirements should link to overall project requirements as appropriate.

Created and Maintained by In most cases scientists are primarily responsible for defining the requirements of model software. The document may be compiled and maintained by a software engineer who is a lead developer.

Template Part of CCSM document template set.

Example Coupler 6 Requirements Document

4.2.2 Architecture Document

Purpose Describes the overall structure of a software component.

Contents $\bullet$ system overview - a high-level description of the software and its relation to other CCSM software
$\bullet$ reference/link to requirements
$\bullet$ architectural strategies and system architecture
$\bullet$ high level interfaces

Created and Maintained by Lead developer(s).

Template Part of CCSM document template set.

Example Coupler 6 Architecture Document

4.2.3 Detailed Design Document

Purpose Used by developers to plan internal and external interfaces before and while the software is being developed.

Contents $\bullet$ API specification, derived types, flag definitions
$\bullet$ description of code function
$\bullet$ reference/link to requirements
$\bullet$ usage examples

Notes We encourage the use of ProTeX to generate the API specification in this document directly from source code.

Created and Maintained by Lead developer(s).

Template Part of CCSM document template set.

Example Time and Date Utility Library

4.2.4 User's Guide

Purpose Explains how to build and run the software.

Contents $\bullet$ a description of the build environment
$\bullet$ a description of any namelist parameters
$\bullet$ a description of any input data
$\bullet$ a description of any output data

Created and Maintained by TBD

Template Part of CCSM document template set.

Example TBD

4.2.5 User's Reference Manual

Purpose Describes the function, interfaces and usage of the software.

Contents API and examples

Created and Maintained by TBD

Template Part of CCSM document template set.

Example TBD

4.3 Planning Documents

4.3.1 CCSM Software Engineering Plan

Purpose To provide a high-level overview of CCSM software engineering goals, schedule, progress, and issues.

Contents $\bullet$ executive summary including a statement of the CCSM project's software objectives
$\bullet$ high-level directions and strategies for software engineering
$\bullet$ descriptions of major initiatives related to the CCSM project and their interrelationships, including what groups are involved in code development
$\bullet$ links to component development plans
$\bullet$ high-level project schedule and milestones

Notes This Software Engineering Plan contains links to Component Development plans. The Component Development Plans will replace the sections found the "Software Restructuring" section of the current Engineering Plan.

Created and Maintained by Currently maintained by authors. Should be updated before SSC meetings or major releases. The project milestone chart in the CCSM Software Engineering Plan should be updated with Component Development Plans.

Template TBD

Example CCSM Software Engineering Plan

4.3.2 Component Development Plan

Purpose Provide a high-level overview of plans and goals for the component.

Contents Development plan including a schedule with major milestones and the groups involved in development.

Notes These Plans are intended to be a few paragraphs at most. The Software Engineering Plan contains links to the Component Development plans.

Created and Maintained by Component's liaison to complete system development team. Should be updated before SSC meetings or major releases. The project milestone chart in the CCSM Software Engineering Plan should be updated with Component Development Plans.

Template TBD

Example Coupler 6 Project Plan

Next: 5 Target Architectures Up: dev_guide Previous: 3 Software Life Cycle Contents

csm@ucar.edu

Purpose	Establishes the functionality required.
Contents	Scientific and computational requirements.
Notes	Component and module requirements should link to overall project requirements as appropriate.
Created and Maintained by	In most cases scientists are primarily responsible for defining the requirements of model software. The document may be compiled and maintained by a software engineer who is a lead developer.
Template	Part of CCSM document template set.
Example	Coupler 6 Requirements Document

Purpose	Describes the overall structure of a software component.
Contents	$\bullet$ system overview - a high-level description of the software and its relation to other CCSM software $\bullet$ reference/link to requirements $\bullet$ architectural strategies and system architecture $\bullet$ high level interfaces
Created and Maintained by	Lead developer(s).
Template	Part of CCSM document template set.
Example	Coupler 6 Architecture Document

Purpose	Used by developers to plan internal and external interfaces before and while the software is being developed.
Contents	$\bullet$ API specification, derived types, flag definitions $\bullet$ description of code function $\bullet$ reference/link to requirements $\bullet$ usage examples
Notes	We encourage the use of ProTeX to generate the API specification in this document directly from source code.
Created and Maintained by	Lead developer(s).
Template	Part of CCSM document template set.
Example	Time and Date Utility Library

Purpose	Explains how to build and run the software.
Contents	$\bullet$ a description of the build environment $\bullet$ a description of any namelist parameters $\bullet$ a description of any input data $\bullet$ a description of any output data
Created and Maintained by	TBD
Template	Part of CCSM document template set.
Example	TBD

Purpose	Describes the function, interfaces and usage of the software.
Contents	API and examples
Created and Maintained by	TBD
Template	Part of CCSM document template set.
Example	TBD

Purpose	To provide a high-level overview of CCSM software engineering goals, schedule, progress, and issues.
Contents	$\bullet$ executive summary including a statement of the CCSM project's software objectives $\bullet$ high-level directions and strategies for software engineering $\bullet$ descriptions of major initiatives related to the CCSM project and their interrelationships, including what groups are involved in code development $\bullet$ links to component development plans $\bullet$ high-level project schedule and milestones
Notes	This Software Engineering Plan contains links to Component Development plans. The Component Development Plans will replace the sections found the "Software Restructuring" section of the current Engineering Plan.
Created and Maintained by	Currently maintained by authors. Should be updated before SSC meetings or major releases. The project milestone chart in the CCSM Software Engineering Plan should be updated with Component Development Plans.
Template	TBD
Example	CCSM Software Engineering Plan

Purpose	Provide a high-level overview of plans and goals for the component.
Contents	Development plan including a schedule with major milestones and the groups involved in development.
Notes	These Plans are intended to be a few paragraphs at most. The Software Engineering Plan contains links to the Component Development plans.
Created and Maintained by	Component's liaison to complete system development team. Should be updated before SSC meetings or major releases. The project milestone chart in the CCSM Software Engineering Plan should be updated with Component Development Plans.
Template	TBD
Example	Coupler 6 Project Plan