Using the Diátaxis Framework to Write Your Project Documentation

Info

In this course, you will not only build software but also document it. The Diátaxis framework (https://diataxis.fr) gives you a simple structure for doing so. It divides documentation into four categories — Tutorials, How-to Guides, Reference, and Explanation. Each has a different purpose, and together they form a complete documentation set for your project.

Think of your documentation like building a table. A table needs both the instructions and the reasoning behind it, just like a software system.

Tutorials are like a blog post showing “how to build a sample table.” It may not be the exact table you need, but it walks you through the basic process so you understand the main steps. In your project, a tutorial should help a new user or developer set up the system and try out the simplest feature. The goal is confidence and a working start, not completeness.

How-to Guides are the IKEA manual. Step 1: attach leg A to board B. Step 2: tighten screw C. At the end, you have the exact table you wanted. For your project, this is where you give clear instructions for specific tasks: how to add a new user, how to run the tests, how to deploy the system. A good how-to guide is short, practical, and always finishes with success.

Reference is the list of all the parts in the box. Four screws of type X, one tabletop of size Y, two brackets of material Z. It’s not a story, it’s a catalogue. In your project documentation, the reference includes API endpoints, configuration options, database schemas, or command-line arguments. It is precise, complete, and objective — the “dictionary” of your system.

Explanations are the design discussion: why this table uses screws instead of glue, why the legs are pine instead of metal, why a certain board thickness was chosen. In your project, explanations are where you describe your architectural choices, trade-offs, and reasoning. This shows understanding and helps future readers (or your instructors) see why the system is the way it is.

Example

Suppose your team builds a task manager app:
- A tutorial shows a new student how to set up the app locally and create their first task.
- A how-to guide gives step-by-step instructions to assign a task to another user.
- A reference lists every API endpoint, with details like POST /tasks or PUT /tasks/{id}.
- An explanation discusses why you chose a REST API instead of GraphQL.

Tip

Do not mix the four types. A how-to guide is not the place for theory, and a reference page should not read like a tutorial. Keep them separate so readers always know what to expect.

By writing your project documentation in these four modes, you make it useful for different kinds of readers: newcomers, active users, maintainers, and reviewers. Just as a well-built table depends on both solid parts and clear instructions, your software project depends on both working code and well-structured documentation.