The documentation for Constellate and the educational notebooks are organized according to a four-part structure inspired by Daniele Procida's presentation at Pycon Australia 2017. Where possible, we have divided the documentation into four categories:

The four categories of documentation: Tutorial, How-To, Reference, and Explanation

In brief, these four categories can be defined as follows:

Tutorial (Learning-oriented)

A carefully constructed example that takes the user by the hand through a series of steps to learn how a process works. Tutorials often use "toy" (or at least carefully constrained) examples that give reliable, accurate, and repeatable results every time.

How-To (Problem-oriented)

A recipe of parts that guides the user through the steps involved in addressing key problems and use-cases. More advanced than tutorials and assumes more basic knowledge. A How-To may use toy examples, but it also gives perspective on how to adapt a process to other common issues or data.

Reference (Information-oriented)

A technical reference for knowledgable users. This may include descriptions of technical material, but assumes the reader is generally knowledgeable on the topic and needs a minimal amount of guidance.

Explanation (Understanding-oriented)

A longer-form discussion of key topics and concepts at a fairly high level, providing useful background information and explanation. Explanations often include images, video, diagrams, and references to lead the reader to other sources of in-depth information.