clairecarouge
(Claire Carouge, ACCESS-NRI Land Modelling Team Lead)
1
This issue discusses the documentation layout for the best user experience. Any suggestions on what sections and pages to have, the order of the sections etc. are welcome.
First proposed layout:
User Guide
Tutorial
Install and compilation
Understand the configuration
Run an experiment
Outputs description
Inputs description
List of inputs
Inputs precedence rules
cable.nml options
pft_params.nml options
cable_soilparm.nml options
Existing configurations
Scientific description
Radiation
Canopy
Soil
Snow
Groundwater
CASA
Developer Guide
CABLE’s Contribution guidelines
Coding standards
CABLE’s release process
API documentation
How-to
How to prepare fields for CABLE
How to work with 1D arrays
MartinDix
(Martin Dix ACCESS-NRI Associate Director for Model Development)
3
I’d like to have the units of all the inputs and outputs documented, both stand-alone and in ESM1-5 and CM2. At the moment the um2netcdf4.py script has to skip setting units for a lot of the CASA-CNP variables because there not clear. E.g. some pool variables claim to be g/m^2. Is this correct or are they kg/m^2? Are fluxes mass of CO2 or mass of carbon?
clairecarouge
(Claire Carouge, ACCESS-NRI Land Modelling Team Lead)
4
We had a CABLE docathon with a few knowledgeable people on CABLE to explore a new platform for the CABLE documentation.
In terms of layout of the documentation, the new platform includes inline documentation based on markup comments in the source code. We decided to have at least a minimum high-level documentation in all the modules and procedures in CABLE.
More details of the science can be added to the inline documentation if needed. However, we haven’t yet decided where the full science documentation will live.
Having the science documentation within the code would facilitate keeping both in sync with each other. But this would mean adding quite lengthy comments in the code which might not be practical and might be contrary to the UM coding standards. We need to check this second point with the UKMO.
More information about the new documentation platform as well as the specifications
of the documentation requirements for the developers will be available soon.
The documentation on the new platform can be found here. This is still very much a work in progress. Anyone who would want to join in the effort is welcome, please contact @clairecarouge or reply to this topic for more information.
clairecarouge
(Claire Carouge, ACCESS-NRI Land Modelling Team Lead)
6
Thanks it’s great to have several examples. We also looked at CLM documentation
It’s interesting how JSBACH put the scientific documentation front and centre and the User guide (installation, running instructions) in appendices.
For the moment, we are thinking to put a lot of the scientific description in line with the code and build it as documentation with FORD. And then have an overview document. So we have less details in a stand-alone page/document and more within the code itself. We think that’s the best way to keep things in sync.
Aidan
(Aidan Heerdegen, ACCESS-NRI Release Team Lead)
7
I like it already for the self-deprecating humility:
One of my hopes if we manage to write a historical carbon cycle paper from our ACCESS-ESM1.5 runs was to have an appendix which mapped CABLE variables through UM output to CMOR-ised variables. Making sure units are documented as well is a good point.
clairecarouge
(Claire Carouge, ACCESS-NRI Land Modelling Team Lead)
9
@RachelLaw I agree we will most likely need additional documentation around the coupled models. Thanks for the input because I don’t know much about the coupled models and what information is missing or not.
