Documentation v2.0

[glwagner]

As HydrostaticFreeSurfaceModel is further developed we're going to have to restructure the docs significantly. In addition to that the docs have grown a bit stale and could probably use a refresh. I think it's a good time too to leverage the year or two of experience we've accumulated using Oceananigans to refactor the docs to make them more useful and practical.

Here's the current structure:

1. Home
2. Installation instructions
3. Using GPUs
4. Examples
5. Physics
6. Numerical implementation
7. Model setup
8. Simulation tips
9. Contributor's guide
10. Gallery
11. References
12. Appendix

I propose refactoring this in a few ways:

• Adding a sort of "quick start" section (perhaps named just that) after "Installation". This will implement a similar simple example as one_dimensional_diffusion.jl, except with even more text, explaining basic important types and functions and providing links to other parts of the docs to obtain more information.
• "Flattening" the model setup section by bringing its sections out into the main list. I think this list should be refactored too according to what's important. For example, we don't need a whole section on Clock.
• Adding independent sections for each model type
• Moving "Physics" and "Numerical implementation" down in the docs to emphasize code documentation.

The resulting structure might be something like

1. What's Oceananigans?
2. Installation
3. Getting started
4. Examples
5. Grids
6. Fields, BoundaryCondition, and AbstractOperations
7. IncompressibleModel
8. HydrostaticFreeSurfaceModel
9. ShallowWaterModel
10. Setting initial conditions
11. Diffusion, viscosity, and TurbulenceClosures
12. Forcing functions
13. Coriolis forces
14. Buoyancy forces
15. OutputWriters
16. OutputReaders, post-processing, and plotting
17. Using Graphics Processing Units (GPUs)
18. Useful tips and common pitfalls (from "simulation tips")
19. Contributor's guide
20. Gallery (this should be way higher eventually, but we need more recent content to motivate that...)
21. Physics and numerical implementation
22. References
23. Appendix

It will take a few PRs to resolve this issue. It'd be great to incorporate feedback on the plan too before making any moves.

[tomchor]

"Flattening" the model setup section by bringing its sections out into the main list.

I agree with absolutely everything except with this. Flattening out the sections makes it hard to situate yourself and find things in the docs. This isn't a problem if you're assuming that users will just read everything from beginning to end, but I think that happens very very rarely, and the overwhelming majority of accesses to the docs are just for consultation.

I remember at some point reading about this and how some (non-rigorous) surveys/studies pointed out a preference for a few nested menus in websites, as opposed to a long flat list of sections. But I can't find it right now and until I can find it again you're free to take this as a personal preference :)

[glwagner]

A more hierarchical organization of the docs is

1. Introduction
   • What's Oceananigans?
   • Installation
   • Writing your first script
   • Do you want to save the world? (by contributing to Oceananigans)
     • Contributing guide
     • Features that need validating
     • Features that need documenting and examples
   • Gallery
2. Examples
3. Building models, running simulations, and post processing
   • Grids and computer architectures
   • Fields, BoundaryCondition, and AbstractOperations
   • IncompressibleModel
   • HydrostaticFreeSurfaceModel
   • ShallowWaterModel
   • Setting initial conditions
   • Diffusion, viscosity, and TurbulenceClosures
   • Forcing functions
   • Coriolis forces
   • Buoyancy forces
   • Simulation
   • OutputWriters
   • OutputReaders, post-processing, and plotting
4. Useful tips
   • Using Graphics Processing Units (GPUs)
   • Common errors and performance pitfalls
5. Fluid dynamics and ocean physics
   • Navier-Stokes and tracer conservation equations
   • The hydrostatic approximation and shallow water equations
   • The Boussinesq approximation and equations of state for seawater
   • Rotating domains and Coriolis forces
   • Diffusion, hyperdiffusion, and parameterization of subgrid processes
     • Basic models for diffusive processes
     • Large eddy simulation
     • Boundary layer parameterization
6. Numerical implementation
   • The finite volume discretization on a staggered grid
   • Interpolation, differencing, and advection schemes
   • Boundary conditions and immersed boundaries
   • The pressure correction method for enforcing mass conservation
   • Discretization of hydrostatic and non-hydrostatic pressure
   • Implicit time-stepping
   • Multi-domain simulations and the cubed sphere
7. Developer guide
8. Appendix
   • References

[glwagner]

This isn't a problem if you're assuming that users will just read everything from beginning to end

That was not my assumption.

My thinking is that a flatter structure is generally easier to navigate for people viewing the docs for the first time, because the overall structure is evident. I think a more hierarchical structure is best for repeated consultation because users "know where they are going". A hierarchical structure could make sense for Oceananigans since it is a complex package. It'd be interesting to hear what others think.

[tomchor]

A more hierarchical organization of the docs is

1. Introduction

   • What's Oceananigans?
   • Installation
   • Writing your first script

2. Examples

3. Model setup

   • Fields, BoundaryCondition, and AbstractOperations
   • IncompressibleModel
   • HydrostaticFreeSurfaceModel
   • ShallowWaterModel
   • Setting initial conditions
   • Diffusion, viscosity, and TurbulenceClosures
   • Forcing functions
   • Coriolis forces
   • Buoyancy forces

4. Simulations and post processing

   • Simulation
   • OutputWriters
   • OutputReaders, post-processing, and plotting

5. Useful tips

   • Using Graphics Processing Units (GPUs)
   • Common errors and performance pitfalls

6. Contributor's guide

7. Gallery (this should be way higher eventually, but we need more recent content to motivate that...)

8. Physics and numerical implementation

9. Appendix

I wholeheartedly agree with this structure :)

[navidcy]

Me too

[francispoulin]

Sorry to be late to the party but I agree, that this change looks great!

I had started writing up notes for the Finite Volume method but suspect it's probably better to hold off before I add this into the docs. Do people agree? If not I think we could add something fairly easily, which could act as a place holder and share some important information until this plan is realized.

[glwagner]

No need to wait until we restructure the docs to add new stuff --- this is a long term plan. There's a place for a finite volume derivation in the docs proposed in this issue, so if its added it will be valued and used. If I'm the one that will be implementing these changes, then they probably won't happen for at least a few weeks, and perhaps a bit more.

[navidcy]

Yeap, let’s add them now and enhance/improve later

[hennyg888]

I'm thinking about updating benchmarks.md with the new benchmark result tables and graphs. Should I do it now or wait until the docs get refactored?
It's only a single file in the appendix section, but I'm not too sure how me opening a PR on it now to update it will affect the grander refactoring plan.

[tomchor]

I'm thinking about updating benchmarks.md with the new benchmark result tables and graphs. Should I do it now or wait until the docs get refactored?
It's only a single file in the appendix section, but I'm not too sure how me opening a PR on it now to update it will affect the grander refactoring plan.

As @glwagner said, this refactoring is a long term plan. I think running new benchmarks now will definitely be a positive change and (imo) a great contribution to the docs ;)

[glwagner]

Hmm, it could make sense to make benchmarking results more prominent. Please feel free to update the benchmarks. More generally I think we need a streamlined way of updating the benchmarks so that we can recreate them easily for (for example) every minor release.

[tomchor]

I was thinking and it might be worth separating the examples between the models. Thus we'd have NonhydrostaticModel examples, ShallowWaterModel examples and HydrostaticModel examples.

[glwagner]

That makes sense to me, especially once we have more than just 1-2 examples for the shallow water and hydrostatic models (these models are still a bit experimental so don't have many examples yet...)