Documentation tree structure and content

[davidorme]

Following on from a recent meeting about documentation, this discussion is to develop a structure for the documentation tree with clear ideas about what goes where and the target audiences. At the moment, we don't have a logical structure and so docs are not being written with a particular reader in mind or are not easy to find by a particular reader.

Documentation structure

The RCS document for the project mentions the Diátaxis framework and that contains four areas that seem like a good starting point. I've loosely grouped what we have or might want to include under those headings:

Tutorials:

• We don't currently have much on this, but these would be aimed at someone wanting to set up and run a VR simulation. That is going to be using the command line interface: a set of input files, some TOML config files and instructions to modify that to get particular outcomes.

How-to guides

This feels like it might two sections:

• How to adapt the tutorial model to implement different scenarios and use cases, or to turn on features. This would all be about changing the configuration and command line settings for running vr from the command line. If this turns into a manual though, it might be better under the Reference section?
• How to use the Python classes and functions. This is more aimed at guiding how to use and extend the API. We have some content here already - notebooks demonstrating the Grid and Data objects.

This area should make heavy use of dynamic notebooks, so that they contain code and explanation to generate actual concrete examples using simple datasets.

Reference

• The main content in here at the moment is the docstring contents, rendered using autodoc. We've got a lot of content in here from the docstrings (some standardisation needed on those - separate topic!).
• One observation here from @alexdewar is that we may be providing too much implementation detail in our docstrings. I think that's right: they can feel somewhere between a docstring and a deeper implementation design note. For the moment, I think recording extra information in the docstrings is fine, provided there is a "how to" to demonstrate use without the complexity of the implementation details, but maybe we need a design notes section. We have a few bits of that already.
• Variable name page - we will have a lot of variables, many of which may live in the same Data object, so we need to be very careful to maintain a central list of those variable names and units.

Explanation

• This is predominantly theoretical explanation - it sets out the science basis for the different models and provides equations, references etc.

Signposting

One thing from the meeting was having a consistent structure/template to provides crosslinks (where appropriate) between different levels of material. Those could just be text links, but we could also use consistent icons for links to the API, HowTo, Science pages.