Closed glwagner closed 1 year ago
"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 :)
A more hierarchical organization of the docs is
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.
A more hierarchical organization of the docs is
Introduction
- What's Oceananigans?
- Installation
- Writing your first script
- Examples
Model setup
- Fields, BoundaryCondition, and AbstractOperations
- IncompressibleModel
- HydrostaticFreeSurfaceModel
- ShallowWaterModel
- Setting initial conditions
- Diffusion, viscosity, and TurbulenceClosures
- Forcing functions
- Coriolis forces
- Buoyancy forces
Simulations and post processing
- Simulation
- OutputWriters
- OutputReaders, post-processing, and plotting
Useful tips
- Using Graphics Processing Units (GPUs)
- Common errors and performance pitfalls
- Contributor's guide
- Gallery (this should be way higher eventually, but we need more recent content to motivate that...)
- Physics and numerical implementation
- Appendix
I wholeheartedly agree with this structure :)
Me too
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.
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.
Yeap, let’s add them now and enhance/improve later
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.
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 ;)
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.
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.
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...)
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:
I propose refactoring this in a few ways:
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.Clock
.The resulting structure might be something like
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.