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.