Documentation content structure#
ArviZ documentation has the Diátaxis as a North Star. This page assumes basic familiarity with Diátaxis.
The ArviZ website is divided into three content blocks:
ArviZ user documentation
ArviZ contributor documentation
ArviZ Project website
ArviZ user documentation#
It is the block formed by the navbar sections
Getting Started, Example Gallery, User Guide and API Reference.
It’s audience are ArviZ users and it uses Diátaxis to achieve its goal of teaching how to use ArviZ.
- Getting Started
The Getting Started section should contain mostly tutorials, however, some how-to content or overview explanations are also allowed and even encouraged
- Example Gallery
The Example Gallery is a visual reference section that should contain no description of the functions used. It should instead link to the API Reference section.
Its goal is to serve as visual index for users who know how their desired plot looks like but not the name of the ArviZ function that generates it
- User Guide
The User Guide is targeted to people who already have basic ArviZ knowledge and should mostly contain how-to guides. It can also contain in-depth explanations and some non-python objects reference content.
- API Reference
It should index and describe all ArviZ objects that are part of the public API, that is, are exposed to ArviZ users. It should be generated from a list of public objects only via sphinx extensions, taking the actual content from the docstrings in each ArviZ object.
ArviZ contributor documentation#
It is all inside the Contributing navbar section.
It’s audience are any and all ArviZ contributors, from new contributors to members of the core team. It follows Diátaxis quite closely by using multiple captioned toctrees.
- Contribution types overview
Diátaxis explanation content. Contributing to ArviZ can be loosely undestood as a single practical craft, but it is more of multiple practical crafts coming together.
This section aims to provide high level overviews explaining different contribution types, what skills are needed for them, why are they important and guide the reader to their next steps in one of the following sections.
- Tutorials
Diátaxis tutorial content. Tutorials with clearly defined and small scope, guiding new contributors in a single “atomic” contribution or even step in the contribution process.
- How-to guides
Diátaxis how-to content. Guides that outline the steps for common processes in the contributing workflow. Documenting this ensures it is available for newcomers but also that all contributors use the same processes which can reduce misunderstanding and frictions.
- Reference
Diátaxis reference content.
- In depth explanations
Diátaxis explanation content.
ArviZ Project website#
It is the block formed by the navbar sections
Community, About Us and by the homepage.
It’s audience is anyone interested in the ArviZ project. This can well be users or contributors but it could also be someone who is neither. It has also no relation to any practical craft and does not follow Diátaxis at all.
It should contain all the information related to the ArviZ community, meeting places (online of physical), shared resources, related projects and communities; and to the project itself, its members, its roadmap, its procedures…