Diátaxis solves problems related to documentation content (what to write), style (how to write it) and architecture (how to organise it).
I recently came across the Diátaxis approach to technical writing. Very cool to read, as it’s essentially just a formalization of the principles that I learned through trial and error during the five years I spent tech writing after college. I highly recommend it to anyone who’s interested in the art of technical communication.
Here’s a cheat sheet I made for my own reference:
Axes of learning
- Action: practical steps
- Cognition: theoretical or propositional knowledge
- Acquisition: study
- Application: work
Content types
Tutorial
- Acquisition + Action
- Helps a user acquire basic competence
- For users who are at study
- Usually the first step on a new user’s learning path
How-to guide
- Application + Action
- Helps an already-competent user perform a particular task
- For users who are at work
- Must be adaptable to real-world use cases
- Omit the unnecessary
Reference
- Application + Cognition
- Helps the user quickly access a list of facts that they need to do things correctly
- For users who are at work
- Free of distraction and interpretation
- Not guides to action
- Usually boring an unmemorable
Explanation1
- Acquisition + Cognition
- Helps the user understand the context and background for what they are doing
- For users who are at study
- The bigger picture
- May contain opinions and perspectives
Workflow
Make changes iteratively, such that they docs are “always complete but never finished.” Remember: perfect is the enemy of done.
- Choose something in docs. (It might be nothing, if you haven’t started it.)
- Ask: is there any way in which it could be improved?
- Decide on one thing you could do right now that would improve it.
- Do that thing.
- And then repeat.
Footnotes
-
When I was working in the field we called these “conceptual docs.” ↩