Your Note Is Trying to Be Four Documents at Once

When a single note conflates tutorial, how-to guide, reference material, and explanation, none of those four jobs get done. The fix is not better organization — it is recognizing that each job serves a different reader-need. Split the note by what the reader is trying to do, not by what the note is about, and the confusion resolves.

That diagnosis comes from Diátaxis, a documentation framework developed by Daniele Procida while working at Divio between 2014 and 2021.¹ It was designed for software product documentation. But Procida has noted that "other people have corresponded with me to share their experience of applying Diátaxis to note-taking systems."² The reason it transfers is that the four reader-needs it identifies are not software-specific — they are universal properties of how practitioners at any skill level encounter new knowledge.

What does a note that "won't behave" actually look like?

A note that resists every organizational system you throw at it is almost always trying to serve four distinct reader-needs inside a single document. It contains step-by-step instructions (tutorial), a recipe for a specific task (how-to), a lookup table of facts (reference), and an explanation of why something works the way it does — all mixed together. None of the four is findable when you need it.

Procida describes the failure mode directly: "When these distinctions are allowed to blur, the different kinds of documentation bleed into each other."³ In the worst case, he writes, there is "a complete or partial collapse" — the note becomes unusable not because it is too short or too long, but because it is trying to answer questions that pull in opposite directions.³

You have probably experienced this as the note that gets longer every time you open it, never feels finished, and is always in the way. The problem is not the length. The problem is that the note has four readers — and you are all four of them at different moments.

What are the four reader-needs?

Diátaxis identifies four distinct needs, and four corresponding forms of documentation — tutorials, how-to guides, technical reference, and explanation.⁴ Each form is defined not by its subject but by two questions: does it serve action or understanding, and does it address a learner or a practitioner?

The framework provides a compass that maps this cleanly.⁵

These four and only four. Procida is explicit: "This is why there are four and only four types of documentation."⁶ The four categories are exhaustive — any note you have ever written falls into at least one of them. An overloaded note falls into all four simultaneously, which is why it cannot be any of them well.

The NumPy project's contributor documentation puts it plainly: "The insight that docs divide up this way belongs to Daniele Procida and his Diátaxis Framework."⁷

How is this different from the advice to use fewer folders?

Two earlier posts on this blog — Stop Filing, Start Finding: Search Beats Folders and Tags or Folders for Your Notes? The Honest Answer — argue against imposing a folder taxonomy on personal notes. A new reader might wonder whether this post contradicts them.

It does not, and the resolution comes from Procida himself.

Those posts argue against creating an empty folder hierarchy before you have written anything — a top-down structure that forces notes into categories they do not naturally belong to. Procida says the same thing about Diátaxis: "Getting started with Diátaxis does not require you to think about dividing up your documentation into four sections… Don't do that. It's horrible."⁸

The distinction is between Diátaxis as a filing system (which Procida explicitly rejects, and which those posts also reject) and Diátaxis as a diagnostic tool — a way to examine an existing overloaded note and ask: what are the distinct reader-needs buried in here? Those are different operations. The procedure below is the second kind. You are not building a taxonomy. You are triaging a note that already exists and is already failing you.

Procida: the framework "is not intended to be a plan… It's a guide."⁹

How to split an overloaded note: the procedure

The following steps work note-by-note. You are not reorganizing your vault. You are operating on one note that has stopped being useful.

Step 1. Read the note once without editing it.

Resist the urge to fix things as you read. The goal is to identify which of the four reader-needs are present. You are looking for passages that answer different kinds of questions: "how do I start," "what is the sequence," "what does this mean," "why does this behave this way."

Step 2. Ask the four diagnostic questions against every paragraph.

Procida provides the question-set directly:¹⁰

• "Can you teach me to…?" — this passage belongs in a tutorial.
• "How do I…?" — this passage belongs in a how-to guide.
• "What is…?" or "What does X mean?" — this belongs in reference.
• "Why…?" or "How does this actually work?" — this belongs in an explanation.

A paragraph that answers more than one of these questions is doing more than one job. Mark it.

Step 3. Create a new file for each distinct need you found.

A note that contained all four might become four files: learning-python-basics.md, how-to-parse-csv-with-python.md, python-standard-library-reference.md, and why-python-uses-significant-whitespace.md. The names signal the purpose — which means you will know which file to open before you open it.

Keep this step mechanical. Do not rewrite yet. Copy and paste the marked passages into the appropriate new files.

Step 4. Link the new files from the original.

Replace the body of the original note with a short paragraph describing what it was trying to do, followed by links to the four new files. The original note becomes an index to its own children. This preserves provenance — you can always see where a piece came from.

Step 5. Prune the original.

Once the child files exist and are linked, delete the copied content from the parent. Do not keep two copies of the same passage. Duplication reintroduces the confusion you just resolved.

Step 6. Edit each new file in isolation.

Now that each file has a single job, you can finish it properly. A tutorial gets a clear learning objective. A how-to guide gets a concrete goal and a numbered sequence. A reference section gets consistent formatting. An explanation gets the space to reason through cause and effect without apologizing for not including a recipe.

A note is a file. You can split it, move it, and rename it without asking an app's permission — that is what open Markdown on your own device makes possible. The procedure above is reversible at any point.

Common mistakes when splitting notes

Making the folder structure first.

The strongest anti-pattern is to create four empty folders labelled Tutorial, How-To, Reference, and Explanation, and then try to sort notes into them. Procida is explicit: "Don't do that. It's horrible."⁸ The folders do not create the clarity — the diagnostic work does. The folders are optional; the questions are not.

Conflating tutorial and how-to.

Procida identifies this as "the single most common conflation": the tutorial and the how-to guide.¹¹ The distinction is that a tutorial is for someone who is at study — learning the domain — while a how-to is for someone at work — already competent and trying to accomplish a specific thing. A tutorial says "by the end of this, you will have done X and know why it matters." A how-to says "here is the sequence of steps to achieve Y." They are different documents even when they share the same subject.

Treating the framework as a scheme rather than a guide.

Procida: "Remember that you are always authoring for a human user, not fulfilling the demands of a scheme."¹² And: "if your execution of Diátaxis leads you to formats that seem uncomfortable or ugly, then you need to use it differently."¹² The four categories are a thinking tool. If splitting a particular note into four does not help you, do not split it into four. The diagnostic questions are still useful even when the answer is "this note only has one job and was fine all along."

Applying the procedure to every note at once.

This is a procedure for a note that is already causing problems. It is not a prescription for your entire vault. The Hacker News community has engaged with the Diátaxis framework three times — with the most recent submission in August 2026 receiving over 525 points and 58 comments, all of it in the context of software documentation.¹³ Nobody in those threads applies the framework to a personal note vault. The note-taking application is a novel use, and the honest scope of this post is one note at a time, not a vault transformation.

How this works with plain files

The procedure above requires only a text editor and a file system. Each new file is a Markdown document. The links between them are ordinary wikilinks or relative paths. No database. No plugin. No sync service.

This is the property that makes the split reversible and composable: each file is independent. You can merge two of them back if the split was wrong. You can move the explanation into a different folder without breaking the how-to. You can open any of the four files in any editor that reads plain text.

The argument that a note is trying to be four documents at once is ultimately an argument about format mismatch — the content has outgrown the container. The container is just a file, and files can be split.

Frequently Asked Questions

What is the Diátaxis framework?

Diátaxis is a documentation framework developed by Daniele Procida, originally for software product documentation, that identifies four distinct types of documentation — tutorials, how-to guides, reference material, and explanation — defined by their relationship to action versus understanding and learning versus application.⁴ Procida reports it has been "adopted successfully in several hundred projects."²

What is the difference between a tutorial and a how-to guide?

A tutorial is for someone who is learning — it teaches a skill, ends with the learner having done something real, and explains why it matters. A how-to guide is for someone who is already competent and needs a sequence of steps to accomplish a specific goal. The tutorial says "by the end of this you will know how to X." The how-to says "to do Y, follow steps 1 through 5." Procida identifies conflating these two as the most common mistake in documentation.¹¹

Do I need to create four folders for my notes?

No. Procida explicitly warns against creating empty four-section structures: "Don't do that. It's horrible."⁸ The diagnostic questions are the tool. Folders are optional and secondary. You can split one overloaded note into four files without changing your folder structure at all.

Can Diátaxis work for personal notes, not just software documentation?

Yes, with honest caveats. Procida notes that people have applied the framework to note-taking systems, but the measured demand for this angle is low — the three Hacker News discussions of Diátaxis that reached the front page, including a 2026 submission with over 525 points, focused entirely on software documentation.¹³ The note-taking application is a legitimate but novel use. Apply it as a diagnostic for a specific note that is failing you, not as a system-wide reorganization.

What if a note only needs one of the four types?

Then it does not need splitting. The diagnostic questions may reveal that a note is already doing one job well. The procedure is for notes that are causing problems — not a prescription applied to every note in a vault.

How do I know when a note needs splitting?

The symptom is that the note grows every time you open it, never feels done, and is hard to find the right passage in when you need it. A second signal: you find yourself skipping sections when you open it because you know what you are looking for is not in that part. When the note has parts you ignore, it has parts that belong elsewhere.

Does this work with any note-taking app?

It works with any system that lets you create new files and link between them. The only hard requirement is that splitting a note into four files does not lose the content — which rules out proprietary formats that cannot be exported to plain text. Plain Markdown files are the natural home for this procedure because each file is independently portable and the links are standard syntax.

How does this relate to Zettelkasten or other note-taking methods?

Zettelkasten focuses on the relationship between atomic ideas across a vault. Diátaxis-as-diagnostic focuses on the internal coherence of a single note — what reader-need it is serving. They operate at different scales and do not conflict. A Zettelkasten note that tries to serve four reader-needs at once has the same problem as any other note that does.

Four reader-needs enter every note you have ever written. When they arrive together, none of them gets what it came for.

The notes you split today stay split — they are plain files on your own device, independent of any app. mnmnote.com

References