[an error occurred while processing this directive] [an error occurred while processing this directive]
CCSM Software Engineering Working Group Meeting Summary
February 27, 2001 at Oak Ridge, TN
Focus: Software-Related Documents
The following is a summary of the CCSM Software Engineering Working Group Meeting (CCSM SEWG). It contains: 1) an overview of the purpose and results of the meeting; 2) a description of some of the tools and guidelines that were mentioned, including URLs; 3) a list of short-term action items.
URLs for the tools discussed at the meeting
are included later in this document. Currently software documents for the CCSM project are being
generated in a variety of formats (LaTeX, Word, html, DocBook), document
content is inconsistent (e.g., "design document" can mean very
different things), and auto-documentation tools are rarely used. Documents are
not that easy to generate, locate, or browse. The point of this SEWG meeting was to come up with a strategy to use
documents more effectively and generate them more efficiently. We proposed general guidelines for any
documents related to CCSM software. We
also proposed a set of basic documents and outlined their applicability and
content. The documents and guidelines
that were presented at the meeting are described at:
The guidelines were accepted with the caveat that some meeting participants wanted to try out the proposed LaTeX-based tools for document generation before committing to a strategy. Comments on these tools or on other aspects of the meeting can be sent to the email@example.com mailing list or posted on the SEWG discussion forum:
We agreed to hold a "barn raising" before the Sixth Annual CCSM Workshop in June, in which a handful of people will instrument the atmospheric model using the ProTeX auto-documentation tool. If this goes well, there was interest in instrumenting the other components in the CCSM as well. We will create and circulate templates and examples for the documents proposed and for module headers. We may explore creating a position in NCAR's Climate and Global Dynamics Division that would include assisting with documents and maintaining the CCSM website.
There were some questions about what the priorities should be in creating some of these software documents. Participants considered defining requirements and architecture for the whole model and large model components important, since this helps to communicate major design decisions. Documenting common utilities was also considered a priority.
2. Guidelines and tools
One of the proposed guidelines is that documents be written in LaTeX, since:
- it is a system many people are already familiar with,
- it produces reasonable print and web documentation using latex2html,
- there is a GUI interface option via the LyX tool, and
- it is compatible with ProTeX, a F90/C auto-documentation tool.
Links to the latex2html, ProTeX, and LyX tools are included
(File List: protex
Some participants were curious about documentation produced using latex2html. Here are some examples:
NWChem: http://www.emsl.pnl.gov:2080/docs/nwchem/doc/user/index.html (thanks to David Bernholdt) MOM: http://www.gfdl.gov/~smg/MOM/MOM_manual.html
3. Action items
1) Try out and comment on tools (if interested, within next two weeks); 2) Create templates and examples for proposed documents (DeLuca/Kauffman with CCSM-programmers, next two weeks); 3) Set date for "barn raising" to instrument atmospheric model and coupler (before June); 4) Explore adding additional staff to assist with and organize documents, help to maintain website (ongoing).
ANL - Argonne National Laboratory
LANL - Los Alamos National Laboratory
ORNL - Oak Ridge National Laboratory
LLNL - Lawrence Livermore National Laboratory
LBL - Lawrence Berkeley Laboratory
NCAR - National Center for Atmospheric Research
NASA - National Aeronautics and Space Administration