Diátaxis

Diátaxis is a systematic framework for technical documentation authoring; "the grand unified theory of documentation".

Modes

The four modes define different forms of documentation, based on the time of use:

They're explained as:

Note that the four modes aren't intended to be "boxes to just shove stuff in": they're methods for understanding the user.

Tutorials

• Targeted at beginners, goal of building basic competence
• Meaningful, attainable
• Learning how, not that: practical, not theoretical
• Teacher and pupil dynamic; exercise must be:
  • meaningful
  • successful
  • logical
  • usefully complete
• Value building confidence
• Don't teach: let the user learn
• Start at the beginning, the user can skim
• Set expectations: outline the achievable goal at the start
• Reliable, repeatable
• Immediate
• Keep explanation and options to a minimum

How-to guides

• Goal-oriented directions to solve a specific real-world problem
• "A close up view of the machinery"
• Clear definition of a process, but without teaching
  • Basic competence an expectation
• Sequence of actions, in order, but not necessarily from the beginning
• Solve a practical problem
• Avoid explaining concepts
• Be general and flexible
• Omit unnecessary detail -- let the reader relate it to concepts
• Aim for discoverability in the title

Explanation

• Discussion clarifying a topic -- optimised for deepening understanding
• No direct use during work
• Since scope is unclear, it's good to have in mind a specific question "why does it work this way?"
• Make connections -- aim to build a web of understanding
• Explain design decisions, design decisions, design constraints
• "About $topic"
• Discuss alternatives
• Don't instruct

Reference

• Austere; succinct descriptions, truth and certainty
• "Like a map"
• Automatic generation ensures accuracy, but can come at the cost of completion and clarity
• Match the structure of the product
• Exclusively describe
• Provide examples

References

• Diátaxis
• Python Docs Community Workshop: Introduction to Diátaxis