Discussion related to CCPP documentation issues

[grantfirl]

• Is the current documentation effective?
• Are there better procedures to follow?

[mkavulich]

Notes from CCPP visioning workshop breakout session:

What works: Documentation on the interface between hosts and schemes (i.e. physics namelist options) is very valuable to physics developers. Tutorial documentation (step-by-step instructions to just get an SCM test case built and run) is very valuable as a jumping-off point to get new users spun up fast.

Improvements that could be made: description of schemes is not enough, physics developers are also interested in interstitial variables, tunable parameters, etc. The SCM technical documentation could use more fleshing out, describing how the code works on a deep level etc. Keeping documentation up-to-date at all times (rather than just at release time) is kind of impossible, and sometimes a waste of effort due to intermediate development and different operational decisions that .

Unanswered questions: Should more dedicated resources (time and personnel) be put towards helping physics developers keep documentation more up-to-date? Should schemes be required to have a corresponding publication? Why do we still use Doxygen? Are there better tools for maintaining and generating inline documentation?

[ligiabernardet]

Would it be interesting to explore the FORtran Documenter (FORD) for inline documentation, as an alternative to Doxygen?

[nusbaume]

Not sure if this is the correct discussion thread, but we at NCAR have started discussing what kind of scheme description info we would like/need for our own CCPP-ized schemes. Do other organizations have required description info or metadata for their physics schemes, beyond the CCPP-framework required metdata (e.g. variable standard names)? If so, would you be willing to share it here? It would be great if we could make sure our schemes match the documentation requirements of other groups.

If you are curious, we currently have an issue with our current list of scheme description needs here: ESCOMP/atmospheric_physics#79

[ligiabernardet]

Jesse, you will find some info at the CCPP Tech Doc here: https://ccpp-techdoc.readthedocs.io/en/latest/CompliantPhysicsParams.html#scientific-documentation-rules

That said, we are planning to host a review of scheme documentation methods before the upcoming CCPP v7 release. So, stay tuned for more discussion.

attn @mzhangw

[nusbaume]

Ahh, I didn't realize this section existed in the Tech Doc, thanks @ligiabernardet! That should definitely help with our own development. Also looking forward to the future scheme documentation review discussion!