A few ideas on the structures of the docs

[tomchor]

I was wondering what's the rationale for the structure of the docs and if someone has thought about changing to something simpler.

Currently the docs are structured roughly like this:

• Intro (home, instructions, GPUs, examples)
• Model setup
• Physics
• Numerical implementation
• Outro (validation, gallery, performance, etc.)

I quite like the intro, and I'm okay with the outro, but the middle part has confused me many times. Basically they kinda cover the same subjects, so there's a lot of overlap in that sense, but also the implementation of each topic is disconnected from their physics/motivation. So when I want to learn about a specific part of the model typically I have to jump around many different sections.

For example if I want to learn about the boundary conditions I first end up in the Model setup/BCs page, which explains how to tell the model which boundary conditions I want. But if I want to get more details I have to jump to the numerical implementation/BCs page to read about what's happening. It feels to me that if they were in the same page (or subsection at least) it would make more logical sense.

Another example happens when the user wants to learn about turbulence closures. There is a page in the model setup section and another one in the physics section. It would make much more to me if those two were in the same page.

I'm not sure why this structure was chosen, but I'd like to get your opinion on a more simpler organization for the middle part of the docs. Basically it would just be a documentation about the model as a whole (or maybe a subdivision might be needed, since now Oceananigans has an IncompressibleModel, a ShallowWaterModel and a HytrostaticModel that simulate different physics). And then in each section would cover a part of the model, first explaining the physics/equations, then giving details on setting it up in the model, and then when appropriate a subsection covering the numerical implementation behind the scenes. Only before a specific part of the model is fully explained from physics to setup/implementation it would move on to another topic.

I think this would make the docs much more comprehensive and I think most of the work for now would be to just move stuff around (instead of actually writing things from scratch).

Thoughts?

[glwagner]

I'm sorry the docs are confusing!

We (mostly @ali-ramadhan with some from me) spent a long time on the docs perhaps a year ago (or more) but have made only incremental improvements since then. The docs are certainly growing increasingly stale at the present moment as we find ourselves focusing on pressing development priorities and new features. They will need a substantial refresh soon (if not now) once HydrostaticFreeSurfaceModel becomes mature and we support curvilinear grids, cubed sphere, and global simulations.

So, it'd be good to flesh out a new outline for docs 2.0 when we are ready to write them.

My opinion is that "model setup" is the core documentation to be used for writing scripts and using the Oceananigans library. It documents types, functions, interfaces, and how to hook things together. It's clearly out of date since we implemented the Simulation feature (quite a long time ago now, but we haven't updated the docs yet). I think it makes sense to dedicate big sections to setting up each model type. It may make sense to wait until we decide whether to merge IncompressibleModel with HydrostaticFreeSurfaceModel or not before making large changes to this section.

I think a separate section dedicated to Simulation, diagnostics, and output writing would also make sense. These features are common to all models and stand alone, since they mainly depend on AbstractField and AbstractOperations functionality. Much of the functionality of AbstractOperations and how fields work together is undocumented (only demonstrated with a handful of incomplete examples).

"Numerical implementation" should be scientific documentation about algorithms used: the finite volume method, interpolation and differencing methods of various orders, fractional step time-stepping methods (which, we discovered, is exceedingly subtle and not well-documented in the literature, so deserving of strong documentation), algorithms for implicit time-stepping (when we have them), etc.

"Physics" more or less contains an explanation of the "continuous" equations that our numerics approximate ("Mathematical models for physical systems" might be a more complete name). I think a description of the LES approximation belongs here, rather than in "Numerical implementation".

For example if I want to learn about the boundary conditions I first end up in the Model setup/BCs page, which explains how to tell the model which boundary conditions I want. But if I want to get more details I have to jump to the numerical implementation/BCs page to read about what's happening. It feels to me that if they were in the same page (or subsection at least) it would make more logical sense.

I think there is a trade-off here that one must be sensitive to. Some users want to know every single detail about what's happening under the hood, to the extent that they might "care" whether a Gradient boundary condition is enforced using halo regions + interior tendency term evaluation, or by the alternative method of directly adding the contribution of diffusive flux + Gradient condition to the boundary-adjacent tendency cells. The results of this choice are (or should be) identical in output, so most users probably wouldn't know the difference between the two, even though it does matter to model developers. I think it makes sense that "Model setup" docs are both detailed enough, but also concise, conveying only the information necessary to write scripts that produce intended results. The line between the two is up for debate, of course, because whether or not users can produce "intended" results depends on the user in question. In the particular case of just how boundary conditions are implemented, I think that the details belong in Numerical Implementation, while the code documentation and information needed to implement a boundary condition in a script belong in "Model setup". But I also think these details are worth discussing for each part of the "Model setup" section, since there is no single rule to follow here and our choices are often a matter of style.

There's a number of related issues, such as #1127.

[tomchor]

I'm sorry the docs are confusing!

Not at all! Just to be clear, I really appreciate the docs! And for the most part I do think they're good and thorough. It's just looking at some specific aspects that are partitioned between Model setup, Physics and Numerical Implementation that I often get confused. (So I'm assuming that also happens to other users, which may not be true.)

I think there is a trade-off here that one must be sensitive to

I completely agree with you that when writing docs you have trade-offs, a lot of things are up for debate, and there isn't a obvious best organization (especially in a code so feature-rich and flexible as Oceananigans). I think what I'm trying to say is that it's less intuitive for a user to read about, for example, specifying BCs in the model and then figure out that he has to go to a whole other section of the docs to read more details about that topic. I myself took a few iterations to figure out that there were (approximately) two pages I had to read for each aspect of the model I wanted to know about.

I think it's also worth mentioning I think that very few users will go through the whole docs. I kinda did (for the most part), but I expect most people to just look for the specific aspect they wanna know about and read that once they find it.