Reformat Decapodes Documentation as a Manual

[quffaro]

Based on a discussion with @jpfairbanks, we'd like to reorganize the Decapodes documentation to be formatted more closely like a Manual. This does not call for revising the content of existing documentation, but consolidating technical knowledge into several new pages.

Currently documentation fills a dual role as both exhibiting Decapodes features and also pedagogy---either demonstrating techniques or carefully reflecting on the modeling process. This pedagogical style means that some techniques may be repeated in the documentation, but it also opens a desire for a more technical, manual-like "single source of truth" reference for using Decapodes.

I am opening this issue to discuss/amend the following proposed structure of the documentation, drafted by @jpfairbanks and myself:

1. Decapodes introduction
2. Operad Algebras
   • O-Compose
   • O-Apply
3. Meshing
4. Operators
   • Defining Custom Operators
   • Composing operators (such as Laplacian as four operators composed)
   • The Manifest from Combinatorial Spaces
   • The generate function
5. Simulations
   • The gensim function
   • evaluation
   • Trouble-shooting (world-age issues, etc.)
6. Initial Conditions and Boundary Conditions (and the plausible role of collages)
7. Plotting and Animations
   • Derived Quantities
8. Error Analysis
9. Tutorial
10. Exhibit (Zoo, if you will)
    • many models
    • migrating the models from "Examples" into here
11. Appendix
    • FAQS
    • ASCII Operators
    • Canon

[lukem12345]

Thanks for opening this issue for discussion. It sounds like most of the docs pages already follow this format, as you are aware. For example, the ice dynamics page appears to follow the manual format already aside from boundary conditions not being necessary.

Introducing a "driving example" through the manual would render it equivalent to another example. Contrapositively, you could create a prototypical manual page by taking a sufficiently fleshed out docs page and removing the particulars of a model. So I want to be sure that the changes proposed in this issue don't repeat an old cycle. ("A real comprehensive docs page has never been tried," as the expression goes.)

The outline of topics to cover are indeed very important, and we would benefit from users of the library being aware of them and proficient in them.

Trying to get at the root issues that we want to address, perhaps having too many docs pages gives off the impression of information overload. I wonder if the experience would be improved by going ahead and deleting half the pages outright, moving them into the examples folder.

It sounds like another sticking point here is that we want to re-arrange the headers on the left banner.

In my experience, I haven't found all that many people actually end up reading through any docs page. I've seen this happen may times, even among internal lab members and collaborators. Of course, this holds for other projects in this organization, and I assume every library experiences this. I even do this myself I assume that this is the actual concern that this current issue is trying to address. Make the docs more approachable so that people will learn the information contained in them. Is that correct?

The current docs are set up such that someone can select the physics problem most useful to them, read through the prose explaining the modeling decisions, and adapt it to their use case. The change proposed in this issue would have the reader learn via a "first-principles" approach; this is a laudable goal. Without more users, it's hard to know how many will fit this bill, though I assume that some would prefer this.

A minor drawback of a first-principles approach is that it puts all information on an equal footing. For example, I see "world age issues" listed here, but I myself have only encountered this once over the past 3 years, and that was due to a bug that was immediately closed.

We could have both examples-based and first-principles extensive documentation. However I worry about information overload issues again. The current FAQ page PR works by linking to where the questions are answered in the docs; this feels like a nice compromise already. Maybe that PR should not be called a FAQ but rather a Manual, and have the headings listed as they would be in a simulation, or that suggested above, rather than at random.

I think another more immediate way of addressing the "real issue" is to inline an example in the README. I'm always partial to small changes with outsized impact.

It should be noted that Decapodes is something of a "seconds to learn, a lifetime to master" framework. We have 3 functions in the library reference, and 2 of them are not meant to be user-facing. The elephant in the room is always going to be the need to learn some physics to know what's going on. The things brought up in this issue would be sufficient for training a julia programmer to compose together reaction-diffusion systems and apply boundary conditions, but they could arrive at this outcome quickly already by copying and pasting the brusselator-bounded script.

[GeorgeR227]

Some things I'd like to bring up as well.

I think we should be thinking about what we want to do with examples versus what we want to do with docs. Recently with #295 I was taking the approach of always "convert examples to docs" since the docs are more user facing and can easily show off the nice visualizations we can get. I think we should really only keep examples of things like CUDA simulations that we can't really run as docs now (but even this could change in the future). I think most of our CPU examples are either fairly old or already doc pages so I would be fine simply removing those. I would also be fine of removing/condensing some docs pages just to reduce their required maintenance.

As for my two cents on "examples-based" and "first-principles", most textbooks I see introduce a learning topic and then follow up with an example. I feel currently our model is flipped from this, in that we introduce the example first and then teach you everything you need to know to implement it yourself. I'm fine with this example first approach since I feel Decapode's primary goal is to showcase that it can complete a wide array of physics while a textbook's primary role is to instruct. Plus, having interesting physics be the most noticeable thing would certainly attract me to read the docs.

But I will say that the overall documentation structure should be better organized to reduce repetition in what we explain. I feel like a combination of this physics-first approach and the long time gaps between new doc pages means that it's simply easier to re-explain a concept in a new page rather than check through other the doc pages to see if it is already adequately explained.

Maybe what we could do is instead have some learning topic tied with a specific physics, and then maybe a zoo of more complicated/cool physics just to showcase them. So we could have, for example, "Starting with the Heat Equation", then "Boundary Conditions with Gray-Scott", "Composition with Budyko-Sellers-Halfar", etc.