Documentation types

We try and follow the Diátaxis approach in organising our documentation. In the Diátaxis scheme, there are 4 broad categories of documentation:

• Tutorials
• How-to guides
• Explanation
• Reference

We have 3 of these directly in the cogent3 docs.

Not all functions need all pieces. For example, data wrangling is the core-business of assembling pieces to do analysis. This warrants both cookbook and example entries. The likelihood modelling does not fit the cookbook well, as it integrates different components and thus requires longer form to build up to each task of interest.

Tutorials

These are our examples. These are for the user in “learning” mode, trying to understand how to stitch things together. When appropriate, these entires should cite original publications. The latter correspond to the “Explanation” diataxis (the missing 4th) type.

Note

Only after confirming citations are not already in cogent3.bib should they be added to that file.

Documentation in this section is in Cogent3/doc/examples. These are longer descriptions with step-by-step instructions. Here's an example.

How-to guides

These are our cookbook entries. These are very short procedural tasks with little exposition. These are for the user in “at work” mode, trying to solve a specific problem.

Documentation in this section is in Cogent3/doc/cookbook. The documentation in this section are small code snippets showing how to do something. They show application to a common case (possibly 2), remarking on relevant parameters and pointing out any gotchas. Here's an example.

References

These are our API docs. These are for the user in “at work” mode, trying to solve a specific problem.

Documentation in this section is in Cogent3/doc/api. To add docs for a data type not currently represented, add a new directory under Cogent3/doc/api. A top-level .rst file matching that data type name should be included and referenced in Cogent3/doc/api/index.rst. Look at Cogent3/doc/api/moltype for an example.

A note about the apps() section

Documentation in this section is in Cogent3/doc/app. This is an experimental interface and is written in the same style as for the Cookbook entries. Here's an example.

Because it's experimental, it's been made a standalone section.

---

🔙 to Contributing documentation