Here's a big page where we can voice high level desires over the direction and design of the overall SciML documentation and the "template" we are using for each of the solver packages.
Package Template
Starting by copying the ModelingToolkit summary of some docs discussions:
This comes after some hefty discussions with users, customers, etc. along with surveys, analytics, and all of that. We'll be rolling out a slightly perturbed style throughout all of the packages, starting with the biggies, being ModelingToolkit and DifferentialEquations.
This comes from some discussions with folks who found the documentation of the following styles to be quite good:
One noticeable aspect is the separation of tutorials from examples. While these all do something slightly different of course, the general mantra is that tutorials are more beginner explanations of core functionality while examples are just "cool shit" you want to show, which maybe has less text. The latter is mostly useful for showing people what you can do, or giving people starter code. The former is more about a human-level explanation. We had been traditionally mixing the two, but it's good to split them so they can serve their respective functions better.
Additionally, for each package we are designating one tutorial to be on top as the "Getting Started" tutorial. The SciML docs as a whole have a "Getting Started" section which we use as a landing page that orients people to the whole ecosystem (https://docs.sciml.ai/Overview/stable/). It's in-depth, multipage, etc. and similar in style to the Pandas or SciPy ones. This then leaves room for the "Getting Started" section of a package to simply be about the package itself. It should have a section at the end that contextualizes, like is seen right now in DifferentialEquations.jl (https://docs.sciml.ai/DiffEqDocs/v7.6/tutorials/ode_example/#Additional-Features-and-Analysis-Tools), but its real focus is "99% of people who use this package should know at least these things". Our Google Analytics shows that >90% of all users read the first tutorial (and about 20% only read the first tutorial in DifferentialEquations, but seem to keep coming back to it!). Thus we basically want a page that will serve as something we "know" or can assume every reader has read. This is why it's then elevated from being the first tutorial to being a separate highlighted "Getting Started" page (which should then also include installation instructions and links to other tutorials / videos).
For ModelingToolkit and DifferentialEquations, and many of our other packages, the first tutorial has already been written as a "Getting Started" type of tutorial, while the other tutorials then dig into specific features. So this PR, like the ones that will happen to other package, elevates the first tutorial to this "Getting Started" status.
That is not to say everything is completed. The matplotlib and MATLAB documentation examples show that associating a plot with each example and putting them in a tiled view is really nice and accessible. We cannot do that with Documenter.jl, so for now we will at least get the examples curated while we beg for some new way to distinguish them from the rest of the documentation. Additionally, I have taken the following notes for documentation improvements, which I'll put here but not actually do yet in this restructuring PR:
- Make as many of the comparisons and explanations into tables. This reduces text and improves readability
- Format examples using more than just headers. Use some bolding, italics. Plots in grids, etc.
- Move plots up, add plots to tutorials
- Make a table introducing all of the modules being used at the top
- Get Documenter.jl to change its default font size from being high school cartoon to something more professional
- Allow more white space in the pages. Space to digest is more important than keeping pages short
- Don't go off template: change the Documenter template because being uniform is more important than being better
Purpose of the SciML Showcase
#92
This is the start of the SciML showcase which was mentioned in #73 (comment) . Thus this PR supersedes #73
What is the SciML Showcase? It's a place for cool demonstrations. Tutorials have to be simple and teaching focused, so it's hard for them to really dive into the fun stuff. But the "why SciML?" is the fun stuff, so that needs to be there front and center somehow. Enter the showcase.
By being separated from the "getting started" section, it's very clear (and has a note) that this is not for getting started. It's saying, hey, you might not understand this code at first glance, but this is to show you all of the cool stuff you'll learn around here! And that's it's main purpose: to show off some cool stuff.
Thus to kick off the showcase, I wanted to revive some of the core examples from the UDE paper and the Bayesian UDE paper, given how those examples seem to be some of the biggest awe drivers to the ecosystem.
That said, the showcase also serves another purpose of making sure that our best examples stay reproducible! Thus the showcase is made for the examples to be run with @example in strict mode, meaning that errors cause failures in the documentation build. I intend for this to be added as a downstream test to all of the major SciML packages that are showcased in the showcase, as this will ensure that any breakage to our top examples are remedied ASAP. This will make our "core" examples much more robust, making it easier for people to share them.
Outside links to track
Related: