Overall documentation style discussions

[ChrisRackauckas]

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:

• https://pandas.pydata.org/docs/index.html
• https://matplotlib.org/stable/index.html
• https://www.mathworks.com/help/matlab/ordinary-differential-equations.html?s_tid=CRUX_topnav

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:

• Move up additional features DiffEqDocs.jl#626
• Download a documentation page as a Pluto notebook JuliaDocs/Documenter.jl#1987
• Support for showing docstrings in @example blocks JuliaDocs/Documenter.jl#1988

[fredrikekre]

[...] the following styles to be quite good [...]

Some of them reminds me of this framwork https://diataxis.fr/ which I tried out for the logging ecosystem at https://julialogging.github.io/

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

Have you seen https://github.com/JuliaDocs/DemoCards.jl, which is used e.g. in the Images ecosystem: https://juliaimages.org/latest/examples/

Get Documenter.jl to change its default font size from being high school cartoon to something more professional

This is the first time I hear anyone complain about the font size. Does "high school cartoon" mean it is too big or too small?

[ChrisRackauckas]

@ArnoStrouwen on the topic of SciML/DiffEqDocs.jl#626, I think the real issue is that we are missing a portion of the template which is crucial for spacing information. If you look at the 3 sample docs:

and now compare that to us:

I'll make it even more obvious by choosing a non-sciml package:

What sticks out like a sore thumb is that Documenter.jl doesn't have a top bar to the menu. It's this fact which then has huge ramifications for the rest of the documentation system! This means that the top level of our manu bar has to be something that says "Tutorial", "Example", etc. You don't really have any other choice for how to organize it because that level has to be there. That means you only have a single level more for organization, and if you use that next level, things are not shown by default.

I don't think the issue is that "additional features" needs to move up in the DifferentialEquations.jl documentation, I think the issue is that trying to cram every single page of a real package's documentation into just a single sidebar is doomed to failure. The older DiffEq documentation was quite ridiculous with a huge sidebar to cover sensitivity, GSA, etc. which we have now fixed by having separate packages. But that's still not enough: even within packages you want to have this kind of granularity. There needs to be a whole API "screen" which has sections of "Problems", "Solvers", ... Examples need to be an entire screen of their own: that is why they were in the SciMLTutorials in the first place!

Examples: They Gotta Move!

Along that note for examples, we also do a poor job at visually communicating what is there. Examples are not informative by titles. Titles tell you what equation is solved, but users don't actually care about solving that equation. Users care about what they will learn in an example, not the equation being solved. So they need some kind of descriptor. See how MATLAB handles it:

with a paragraph. I think some kind of tagging system to you can filter "events/callbacks", "ode", etc. would be a really nice improvement to this idea.

I tend to like the MATLAB one better than the matplotlib one, since it's more informative.

[ChrisRackauckas]

Have you seen https://github.com/JuliaDocs/DemoCards.jl, which is used e.g. in the Images ecosystem: https://juliaimages.org/latest/examples/

I had not seen that. That looks really good, though I'd be curious how to setup tagging and filtering as described above.

This is the first time I hear anyone complain about the font size. Does "high school cartoon" mean it is too big or too small?

@bauglir will chime in with some comments on the font size. I guess MATLAB is the outlier here in terms of main text, but we're the outlier in terms of sidebar text. That picture of the top of the DiffEq page has only 2 tutorials fit onto the screen with non of the other links (examples, problems, solvers, manual, API, ...) even able to make it onto the screen. Our sidebar is a good few chunks larger than the other ones, so all of the titles tend to wrap to new lines.

[bauglir]

Some of them reminds me of this framwork diataxis.fr which I tried out for the logging ecosystem at julialogging.github.io

Looks like that's the original definition, thanks for sharing. I had seen it in the context of this page and it's been something we have indeed been talking about.

As for the font size. I think it's important that we take well researched design guidelines into account. Doing some basic research, in this case it's indeed the documentation of the MathWorks that's the outlier, using a 13px font-size for body text. Looking at the documentation in other programming language ecosystems, such as Node.js, Python/Read the Docs, Go, Rust, Ruby, GitBook, all use 16px as their body text font-size. The same as Documenter.jl.

The value of 16px can be directly derived from well established typography guidelines. Slightly dependent on the font used, it's the equivalent of a 12 point size in print. According to the Practical Typography website a size of 10-12 points is optimal for print. How this translates to the web depends on the type of device used. For desktops a direct translation from point to pixels (i.e. times 1.333...) may be sufficient, but for mobile devices the font-size should be slightly increased. Compare, for instance, the guidance on font sizes in Adobe's Spectrum design system. In Google's Material Design design system 16px corresponds to "large body text". As a final note, MathWork's 13px is the equivalent of a 9.75 point size which falls outside most of the given ranges.

Accessibility is also something that should be taken into account. One source of information here are the US government's accessibility guidelines on typography which also recommends using at least a 16px "effective" font size for body content.

That being said, all of this is about body text. For other types of text, especially if it's shorter in length such as menu items, etc. it should be possible to use a smaller font-size.

In addition to light/dark mode switches I used to see small/medium/large font selectors on sites, but apparently those are no longer "a thing". If we can find some examples of those, perhaps that'd be something that could be baked into Documenter.jl where medium is 16px. A basic version of that shouldn't be incredibly hard to implement. But I'd be a bit weary about the fact that I don't seem to be able to easily find an example of those anymore 😅. Perhaps these have gone out of fashion in favor over using zooming capabilities in browsers directly.

[bauglir]

When the documentation of SciML packages is read through https://docs.sciml.ai, perhaps the logo of the individual component should also be hidden? This is relatively straightforward to achieve using some CSS. It doesn't save a lot, but it gives back some vertical space in the sidebar.

[ChrisRackauckas]

That's a good point.

[storopoli]

If I may chime in.

I've seen in one of the ACoP workshops the use of a Tabset Panel in a Quarto document to showcase different examples of the same concept.

I think that this resource is quite interest to have in documentation since whenever we are showing/documenting several ways to solve/represent the same concept/issue we avoid having the user to perform vertical up and down scrolling and instead we rely on tabs. I think that for some use cases it would reduce the cognitive load of a user reading a technical document that presents different approaches.

[ArnoStrouwen]

The tables are in my opinion hard to read. There is barely any differentiation between the header and the remaining rows.
I am also not a fan of the alignment to the right.

Compare this with the github source page, which for me is much easier to parse.

[j-fu]

There is also Pollen.jl by @lorenzoh.

As for a kind of wish: integration of Pluto notebooks with documentation - IMHO they are well suited for tutorials and examples. In this context,
on the Pluto side, see e.g. this dicussion: fonsp/Pluto.jl#1345