What documentation layout should we use for CABLE

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

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?

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.

Hi,

I always found the JSBACH technical documentation to be very good. Perhaps it can be used as an example on how to structure the CABLE documentation.

https://pure.mpg.de/rest/items/item_3279802_22/component/file_3316522/content

Cheers,
Tam

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.

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.

@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.