Workshop 4 - Documentation discussion

[chporter]

2021-06-01

[chporter]

Be consistent about categories of documentation . The 3 items listed in the goals should match categories below.

[chporter]

Include overview in list of categories in goals.

[chporter]

Documentation of a model - specific to version #. Provenance / history important.

[chporter]

version history should be included in documentation / change log.

[chporter]

Step-by-step documentation (metadata) instructions.
Example from med community: 5 steps (easy to remember steps).
Coarser-grained list of metadata steps.

[chporter]

e.g., ID: Space, Time,
Science
Software
Platform / language
Semantic
Syntactic
...

[LuS-GitHub]

visual representation of documentation steps for quick grasp of overall process

[percivall]

Possible Categories of model metadata:

• Source and owner organization. Who created it
• Semantic or Science description: science domain, definition of phenomenon/variables/Units of Measure/, basis/theory of algorithms, domain of validity (spatial (e.g., only at the poles), temporal (e.g. timestep no smaller than a year.)
• Internal code structures: models and their dependencies, programming language, libraries
• External code interfaces and data encodings
  Consider reuse existing relevant metadata standards, e.g., ISO TC 211 Geographic data set metadata (ISO 19115)

[chporter]

Documentation should be easily searchable.

[percivall]

Consider requiring that the document be web-friendly, e.g., written in html.

[chporter]

Bullet point: Harmonization with schema.org and codemeta metadata vocabularies
Remove "schema.org"?

[chporter]

Recognized properties for CodeMeta Code includes terms from https://schema.org. These terms are part of the CodeMeta specification and can be used without any prefix.
https://codemeta.github.io/terms/
So it does seem redundant to include both, especially when the link is to CodeMeta only.

[chporter]

Turned this into an issue and suggested edit.

[cmbarton]

Issue #298 (closed with commit)

[chporter]

Model theoretical documentation - include list of publications, (may be version-dependent)

[chporter]

(include under open access bullet)

[chporter]

Reverse order of "Model Documentation" and "Sample Applications"

[chporter]

suggested this edit 2021-06-02

[cpritcha]

Examples of good documentation for non-modeling projects (searchable, good tutorials, code samples, how to)

• vuejs.org
• https://jupyterbook.org/intro.html

[cpritcha]

Good documentation should have tutorials and a cookbook so you can see the model being set up for different scenarios.

[chporter]

Overview - processes modeled - maybe more generic wording.

[chporter]

To facilitate model interoperability, map variables between components and with equations in publications.
e.g. q mapped to discharge (or ontology name)
if applicable.

[chporter]

consider splitting into "basic" and "advanced" sections.

[chporter]

Audiences for model documentation may need different kinds of documentation.
non-technical
modeler
model developer

[franklinzhanggis]

Maybe we can have a structural document (such as XML/Json file) that can be formatted to different kinds of documentation

[chporter]

Include checklist for objective review of models.

[hsu000001]

Here is an example of an implementation this documentation for the USGS Model Catalog - https://github.com/usgs/modelcatalog-tam ; You will see the Basic Profile schema here: https://github.com/usgs/modelcatalog-tam/blob/main/metadata_schema/BasicProfileSchema.py , there is a PR to add the Advanced Profile.

Some modifications were made to help pull in information from other USGS systems....

This Basic Profile is running https://data.usgs.gov/modelcatalog/ ("under development"... many fields are not yet displayed...)

[chporter]

"All data dependencies needed to run the model and replicate any published results"
Will not be possible for large, complex models with hundreds of publications over decades.

Even for a simple model, this doesn't belong in metadata.

[chporter]

Concept of nested documentation for large complex models.
e.g., 1-pager for overall model, one each for various sub-components.
Same for metadata, Methods, etc.

Are there examples in climate modeling community?

[chporter]

Model application classification - is there an international standard vocabulary?
Could use multiple classification systems, e.g., Australian, Chinese.

[chporter]

Australian and New Zealand Standard Industrial Classification, for example.