documentation structuring

[jhidding]

much of the documentation is a bit scatter around right now. there needs to be clear entry points for the following:

• architecture (understanding components and models)
• tutorial, see Tutorial #64
• visualizations
• api, see determine public API and document it #54
• literacy in model presentation: currently the model presentations are a bit stripped of their literate character. The BS92, Burgess13 and Active Layer, Denudation sections are good places to document the production model, CA, transport code and denudation respectively.

[EmiliaJarochowska]

I would like to contribute to the last point. Do you have instructions on how a literate model presentation should look like?

[jhidding]

Not really, I'm figuring this out as we go along. What works best, I think, is when the documentation follows the motivation. The model code would be closest to a literature review: reproducing BS92, B13 and demonstrating HJX25 and XJH25 (et al). The material is now scattered:

• BS92: currently most complete
• B13: ca-with-production.md, carbocat.md, also introduces stencils.md
• ALCAP: active-layer-transport.md, model-alcap.md, also introduces sediment-buffer.md
• Denudation: everything in denudation folder. WithDenudation.jl needs redesign in components.

These follow a narrative of increasing complexity introducing new elements as we go along.