ChrisRackauckas
commented
1 year ago https://docs.sciml.ai/PolyChaos/stable/multiple_discretization/ is kind of a weird one, so I wouldn't start there. I think DifferentialEquations.jl is a good one to start with. So let's say we were here:
https://docs.sciml.ai/DiffEqDocs/stable/getting_started/
Notice that the sidebar is cramped. We first have a getting started and then a few tutorials but everything else doesn't even fit into a big screen. Also, there's an Examples section but it cannot show any information of what's in there because it's too cramped, so we cannot do something like https://github.com/JuliaDocs/DemoCards.jl.
What we'd want to do is have a Getting Started/Tutorials section which has all of the highest level information and the tutorials. Then a user guide section would have all of the sections like "Basics" and "Additional Features". Then we want to do an examples section with demo cards to make it easy to navigate. Then we'd want an API section that had "Problem Types" and "Solver Algorithms", along with an advanced API section which has the detailed solver APIs pages along with the entire new docs https://docs.sciml.ai/OrdinaryDiffEq/stable/ which is more solver API docs that we have no idea how to stuff onto the current pages. Maybe "Detailed Solver Information" could be its own bucket. Then a contributors section would have what's right now this separate documentation https://docs.sciml.ai/DiffEqDevDocs/stable/. And then a release notes section would be nice.
So as you can see, right now it's all just stuffed into the sidebar + 2 separate documentations that bring this all together, since we are missing a higher level navigation. I think we'd start by doing this same thing to each of the solvers libraries, and then work through SciMLSensitivity as another that has a ton of content, do the same thing, then one by one make them all flow in this form.
Forking off this discussion from #108, I wrote up some thoughts on implementing the top navbar into Documenter: https://github.com/JuliaDocs/Documenter.jl/issues/2177
What I would love, though, is to more precisely understand how we would like to use it for SciML. Do we have a rough sketch of what the navigation would look like for the SciML manual in the ideal world? E.g. what would we see if we would be on, say, these pages?