Diataxis #

XXX: we’re not really following this, but keeping it around in the archive for now at least.

The content is structured with respect to both ST documentation artefacts and the four types of documentation content defined by Diátaxis.

• The documentation artefacts

  • High level intuitive description (overview, A.6.4.)
  • “System documentation” [1][] (sysdoc, A.6.5.)
  • Specification (spec, A.6.3.)
  • Design (design, A.6.2.)
  • Vision (vision, A.6.1.)
  • Documentation of each individual code artefact, outside of this repo (artefacts)

• The four documentation content types

  • Tutorials
  • How-to guides
  • Reference
  • Explanation

  Example: https://ubuntu.com/core/docs/

[1] Connecting the high level description to documentation belonging to each ST code artefact involved. This seems like it will become the kitchen sink.

How to write documentation #

The following guidelines are inspired by Diátaxis and further sets some language styles to be consistent in ou documentation.

How To Guides #

For the essence of a How To Guide see Diátaxis

• This guide shows you how to…

  Describe clearly the problem or task that the guide shows the user how to solve.

• If you want x, do y. To achieve w, do z.

  Use conditional imperatives.

• Refer to the x reference guide for a full list of options.

  Don’t pollute your practical how-to guide with every possible thing the user might do related to x.

• You need to install x Install x

  Do not use personal subjects.

Tutorials #

For the essence of a Tutorial see Diátaxis

• In this tutorial, you will…

  Describe what the learner will accomplish (note - not: “you will learn…”).

• First, do x. Now, do y. Now that you have done y, do z.

  No room for ambiguity or doubt.

• We must always do x before we do y because… (see Explanation for more details).

  Provide minimal explanation of actions in the most basic language possible. Link to more detailed explanation.

• The output should look something like this…

  Give your learner clear expectations.

• Notice that… Remember that…

  Give your learner plenty of clues to help confirm they are on the right track and orient themselves.

• You have built a secure, three-layer hylomorphic stasis engine…

  Describe (and admire, in a mild way) what your learner has accomplished (note - not: “you have learned…”)

Explanation #

For the essence of Explanation see Diátaxis

The reason for x is because historically, y… Explain.

• W is better than z, because…

  Offer judgements and even opinions where appropriate..

• An x in system y is analogous to a w in system z. However…

  Provide context that helps the reader.

• Some users prefer w (because z). This can be a good approach, but…

  Weigh up alternatives.

• An x interacts with a y as follows:…

  Unfold the machinery’s internal secrets, to help understand why something does what it does.

Reference #

For the essence of Reference see Diátaxis

• X is an example of y. W needs to be initialised using z. This option does that.

  State facts about the machinery and its behaviour.

• Sub-commands are: a, b, c, d, e, f.

  List commands, options, operations, features, flags, limitations, error messages, etc.

• You must use a. You must not apply b unless c. Never d.

  Provide warnings where appropriate.