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.
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.
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:
Below are descriptions of the recommended development documents with guidelines on content. Templates for the documents are available at:
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 | system overview - a high-level description of the software and its relation to other CCSM software reference/link to requirements architectural strategies and system architecture 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 | API specification, derived types, flag definitions description of code function reference/link to requirements 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 | a description of the build environment a description of any namelist parameters a description of any input data 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 | executive summary including a statement of the CCSM project's software objectives high-level directions and strategies for software engineering descriptions of major initiatives related to the CCSM project and their interrelationships, including what groups are involved in code development links to component development plans 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 |