How-to guides

[pmli]

• adds two how-to guides (about running demos and converting NumPy arrays to NumpyVectorArrays)
• removes "running demos" section from Getting Started
• reorders docs sections
• renames "pyMOR Tutorials" to "Tutorials"

[HenKlei]

Is the rendered documentation available somewhere? It seems like it was not uploaded.

[pmli]

It seems like docs deployments started failing recently: https://github.com/pymor/docs/commits/main/

At least, it seems like it is possible to access it via ZIV GitLab: https://pymor.zivgitlabpages.uni-muenster.de/-/pymor/-/jobs/1798414/artifacts/docs/_build/html/index.html

[artpelling]

I think it would be helpful to also show how to convert back. Especially that you need to transpose.

[pmli]

I'm not sure if it fits here or if would be better to have a general "How to convert a VectorArray to a NumPy array?" guide (which would mention that NumpyVectorArrays have an array attribute, and that in general there is the to_numpy method which need not be implemented).

[sdrave]

Before moving forward with this, I'd really like to further discuss if we want this. IMHO, there should be a 'working with VectorArrays' tutorial, which I intend to write at some point. If there is such an tutorial, do we want to duplicate the information here? The two concerns I have:

1. Nobody wants to write documentation. Maintaining existing documentation even less. The 'technichal overview' is a good example how documentation can rot. So the amount of text should be kept at a minimum.
2. I have seen several cases of documentation featuring different categories like (howto, getting started, examples, in-depth information, etc.), where I was really confused where to look to find a specific piece of information. As such, I would really like clearly defined entry points to the documentation. The separation between 'how to' and 'tutorial' seems to vague to me.

[HenKlei]

In general I am not sure if we need the "How-to guides" in the end. I am always a bit lost where to look for information when having the API documentation, tutorials, how-to guides and so on. If possible, I would be for reducing the number of different resources of information to a minimum.

In this specific case, the VectorArrays will hopefully be explained in more detail in a separate tutorial (I think @sdrave is planning to write such a tutorial) which should serve as the first reference. In particular since an additional how-to guide also has to be maintained and kept up to date.

Maybe it could be an option to mainly refer (in the how-to guides) to specific points in tutorials where one can find the detailed information without having to write another how-to guide.

[pmli]

I agree that it should be clear to documentation readers (and writers) what is the point of how-to guides. To be honest, I have difficulty understanding how the medical analogy from Diátaxis applies to pyMOR. The best thing I could come up with is for how-to guides to be similar to a checklist (like the release checklists). For pyMOR, this could be a checklist for implementing new Operators (what methods are necessary and if to_matrix/projection should be extended) or for implementing interfaces to external solvers. Maybe we can discuss this in the next community meeting.