Hinata Wiki

Appearance

Diátaxis — Documentation Classification Reference A systematic approach to documentation that serves practitioners in a domain of skill. Based on Daniele Procida's framework. Diátaxis identifies four distinct documentation needs arising from two dimensions of craft. Every piece of documentation serves exactly one of these needs. Mixing them degrades all of them.

Type Orientation Purpose Question Answered Analogy Tutorial Learning Provide a learning experience "Can you teach me to…?" Teaching a child to cook How-to Goals Help achieve a particular goal "How do I…?" A recipe in a cookbook Reference Information Describe the machinery "What is…?" Information on a food packet Explanation Understanding Illuminate a topic "Why…?" An article on culinary history The Compass — Classification Decision Tree When unsure which type a piece of documentation is (or should be), answer two questions. The intersection gives you the type.

Acquisition (study) Application (work) Action (doing) Tutorial "Teach me to do this" How-to Guide "Help me accomplish this" Cognition (thinking) Explanation "Help me understand this" Reference "Tell me the facts about this" Using the Compass Question 1: Does this content inform action (practical steps, doing things) or cognition (theoretical knowledge, thinking about things)?

Question 2: Does this content serve the acquisition of skill (studying, learning) or the application of skill (working, getting things done)?

Apply these at the sentence, paragraph, section, and document level. Misclassification at any level is a quality defect.

The Map — Relationships Between Types The four types exist in a two-dimensional space, not a list. Neighbouring types share one dimension and differ on the other, which is why they are easily confused.

Shared Dimension Adjacent Types What They Share What Distinguishes Them Guide action Tutorial ↔ How-to Both contain practical steps Study vs work; managed path vs real-world branching Serve application How-to ↔ Reference Both serve the working practitioner Doing vs knowing; steps vs descriptions Propositional knowledge Reference ↔ Explanation Both inform cognition Lookup while working vs reading to understand Serve acquisition Explanation ↔ Tutorial Both serve the studying practitioner Thinking vs doing; reflection vs action The Journey Around the Map Practitioners cycle through phases: learn (tutorial) → apply (how-to) → look up (reference) → reflect (explanation) → back to learning. This is not a rigid sequence — a practitioner enters at any point — but it describes the natural progression from novice to expert.

Tutorials — Learning-Oriented Defining Qualities Purpose Provide a learning experience under guidance User state At study — acquiring skills Obligation The learner's success is the teacher's responsibility Voice First-person plural: "We will…", "Now we…" Structure Single linear path — no forks, no choices Explanation Minimal — link to explanation, do not inline it Outcome The learner has done something meaningful and gained confidence Key Principles Show where they'll end up — "In this tutorial we will create X. Along the way we will encounter Y." Deliver visible results early and often — every step produces something the learner can see and understand. Maintain a narrative of the expected — "You will notice that…", "The output should look like…" Point out what to notice — prompt observation; learners are too focused on doing to notice on their own. Encourage repetition — make it possible to repeat steps; repetition is foundational to learning. Ruthlessly minimise explanation — "We use HTTPS because it's more secure" + link. No more. Focus on the concrete — this problem, this action, this result. Ignore options and alternatives — one path to one conclusion. Aspire to perfect reliability — every learner, every time, gets the expected result. Anti-pedagogical temptations (resist these) Abstraction, generalisation, explanation, choices, information. The first rule of teaching: don't try to teach. Provide the experience; trust that learning will happen.

How-to Guides — Goal-Oriented Defining Qualities Purpose Help the already-competent user accomplish a specific task User state At work — applying skills Obligation Guide the user's action toward a successful result Voice Conditional imperative: "If you want X, do Y. To achieve W, do Z." Structure A series of steps, potentially branching: "If this, then that" Explanation None — link to explanation and reference, do not inline Outcome The user has completed a real-world task correctly Key Principles Address real-world complexity — adaptable to actual use cases, not just the narrow example. Omit the unnecessary — practical usability over completeness; start and end in reasonable places. Provide a set of instructions — an executable solution including thinking and judgement, not just clicks. Describe a logical sequence — order matters; put environment setup before the operation it enables. Seek flow — smooth progress; minimise context-switching; anticipate the user's next thought. Pay attention to naming — "How to integrate APM" (good) vs "Application performance monitoring" (bad — is it about how, or what?). How-to vs Tutorial — The Critical Distinction A tutorial is a lesson (safe, managed, learning-oriented). A how-to is a recipe (real-world, goal-oriented, assumes competence). A professional chef follows a recipe — that doesn't make it a lesson. Someone expecting a recipe who gets a cooking lesson will be annoyed.

Reference — Information-Oriented Defining Qualities Purpose Describe the machinery — as succinctly and accurately as possible User state At work — needs truth and certainty to stand on while working Obligation Be wholly authoritative — no doubt, no ambiguity Voice Declarative present tense: "X accepts Y. Returns Z." Structure Mirrors the structure of the thing it describes Explanation None — describe and only describe; link to explanation Outcome The user has found the authoritative fact they needed Key Principles Describe and only describe — neutral, objective, factual. Resist explaining, instructing, discussing, opining. Adopt standard patterns — consistent format across all reference pages of the same kind. No creativity in structure. Respect the structure of the machinery — documentation structure mirrors the thing it documents. Provide examples — illustrative examples prevent the need for instruction or explanation while staying descriptive. Be austere — one hardly reads reference material; one consults it. Trim every unnecessary word. Critical for Agents Reference is the type most consumed by agents during work. Every line in a reference file is treated as an authoritative fact. If rationale ("we chose X because…") or opinion ("X is better than Y") leaks into reference, agents will treat subjective prose as hard truth — the primary hallucination vector.

Explanation — Understanding-Oriented Defining Qualities Purpose Deepen and broaden understanding; illuminate a topic User state At study — reflecting on practice, away from the keyboard Obligation Bring clarity, light, and context through discursive treatment Voice Discursive: "The reason for X is because historically, Y…" Structure Topic-centred — "About X"; open-ended but bounded Instruction None — no steps to follow; link to how-to guides and tutorials Outcome The reader's understanding is richer and deeper Key Principles Make connections — weave a web of understanding; link to other topics even outside the immediate domain. Provide context — design decisions, historical reasons, technical constraints, implications. Talk about the subject — the bigger picture, history, choices, alternatives, reasons and justifications. Admit opinion and perspective — understanding requires acknowledging that other perspectives exist; weigh alternatives. Keep it closely bounded — resist absorbing instruction or reference; those have their own homes. Naming Test You should be able to place "About" in front of every explanation title: "About user authentication", "About database connection policies." If "About" doesn't fit, it's probably not explanation.

Anti-Blur Rules — Preventing Type Contamination Blur — the bleeding of one documentation type into another — is the primary structural failure in documentation. Each adjacent pair has a natural tendency to collapse into the other.

The Six Canonical Blurs Tutorial absorbs explanation → Move "why" to an explanation page. Keep only "We use HTTPS because it's safer" + link. Tutorial absorbs how-to → Tutorials follow one path; if branches appear ("you could also…"), extract to a how-to. How-to absorbs explanation → Strip rationale from steps. "Do X" not "Do X because historically Y and some prefer Z." How-to absorbs reference → Remove exhaustive parameter tables; link to reference. Show only the parameters this task needs. Reference absorbs explanation → Strip all "why" from reference. Move rationale, opinion, and context to a linked explanation. Explanation absorbs how-to → Remove step-by-step instructions from explanation. Link to the relevant how-to instead. Blur Detection Heuristics Signal Probable Blur Fix Long reference file (>200 lines of prose) Reference ← Explanation Extract prose to explanation; keep reference austere "You could also…" in a tutorial Tutorial ← How-to Remove alternatives; one path only "The reason we…" in a how-to How-to ← Explanation Strip rationale; link to explanation Parameter tables in a how-to How-to ← Reference Show only needed params; link to full reference "Step 1: …" in an explanation Explanation ← How-to Remove steps; link to how-to Opinion or hedging in reference Reference ← Explanation Remove opinion; state facts only Quality Theory Functional Quality (Objective — Measurable) Accuracy, completeness, consistency, usefulness, precision. These are independent: documentation can be accurate but incomplete, or complete but inconsistent. Functional quality is necessary but not sufficient.

Deep Quality (Subjective — Felt) Feeling good to use, having flow, fitting human needs, anticipating the user. Deep quality is interdependent (flow and anticipation are aspects of each other), conditional on functional quality (can't feel good if inaccurate), and arises from liberation rather than constraint.

Diátaxis and Quality Diátaxis addresses deep quality by describing documentation modes based on user needs. It preserves flow by preventing the disruption that occurs when content runs across the user's purpose (e.g. explanation interrupting a how-to). It exposes lapses in functional quality by making gaps and inconsistencies visible through clear structure.

Frontmatter Schema — Machine-Readable Classification Every file carries metadata that declares its type, enabling automated classification, agent consumption mode selection, and vault-wide auditing.

Required Fields ​

title: "Document Title" type: tutorial | how-to | reference | explanation craft: action | cognition stage: acquisition | application status: draft | active | superseded summary: "≤160 chars — what this file is, for progressive-disclosure routing" ​

Self-Validation type craft stage Valid? tutorial action acquisition ✓ how-to action application ✓ reference cognition application ✓ explanation cognition acquisition ✓ reference action acquisition ✗ — misclassified Optional Fields authority: canonical | derived | scratch domain: "entity or topic this file belongs to" last-reviewed: YYYY-MM-DD retain: permanent | 30d | 7d depends-on: "other-file" supersedes: "old-file" aliases: [alternate-name-1, alternate-name-2] Per-Type Templates ​

TUTORIAL ​

title: "Learn to [X]" type: tutorial craft: action stage: acquisition status: active summary: "Walk through creating X" ​

Learn to [X] ​

TUTORIAL — follow along step by step

What we'll build ​

Step 1 ​

Step 2 ​

What you've accomplished ​

HOW-TO ​

title: "How to [X]" type: how-to craft: action stage: application status: active summary: "Steps to accomplish X" depends-on: "prerequisite" ​

How to [X] ​

HOW-TO — goal-oriented steps

Prerequisites ​

Steps ​

Troubleshooting ​

REFERENCE ​

title: "[Entity/System Name]" type: reference craft: cognition stage: application status: active authority: canonical summary: "Facts about X" ​

[Entity Name] ​

REFERENCE — facts only, consult while working

Properties ​

Behaviour ​

Constraints ​

EXPLANATION ​

title: "About [Topic]" type: explanation craft: cognition stage: acquisition status: active summary: "Why X works the way it does" ​

About [Topic] ​

EXPLANATION — understanding-oriented

Context ​

How it works ​

Design decisions ​

Trade-offs ​

Alternatives considered ​

Authoring Guide — Per-Type Writing Rules Voice and Tense by Type Type Voice Tense Example Tutorial First-person plural Present + future "We will create a file. Now we add…" How-to Conditional imperative Present imperative "If you want X, do Y. Run the command." Reference Third-person declarative Present "X accepts Y. Returns Z. Raises W if…" Explanation Discursive / editorial Mixed "The reason for X is historically…" Linking Rules by Type From Type Links To Never Links To Tutorial Explanation (for the curious), Reference (for lookup) Other tutorials, alternatives How-to Reference (parameters), Explanation (background), other How-tos (next steps) Tutorials (don't teach mid-task) Reference Other Reference (related entities), Explanation (context), How-to (usage examples) Tutorials (don't teach) Explanation Reference (facts cited), How-to (practical application), other Explanation (related topics) Tutorials (don't teach) Token Density by Type Type Target Density Prose Style Max Length Guideline Tutorial Medium — step + expected result pairs Conversational, concrete No hard cap — as long as the lesson needs How-to High — pure action + conditionals Terse imperative ≤ what the task requires; trim preamble Reference Maximum — tables, lists, key:value Austere declarative ≤200 lines per file; split at entity boundary Explanation Lower — prose-first, discursive Rich, contextual, editorial Bounded by topic; one topic per file Agent Implications — Why Classification Prevents Hallucination When an AI agent loads vault documentation as working memory, the type field is a consumption-mode selector:

type Agent Consumption Mode Failure if Misclassified reference Every line is an authoritative fact; cite directly If explanation bleeds in → agent cites opinion as fact how-to Execute steps in sequence; respect conditionals If explanation bleeds in → agent tries to execute prose tutorial Follow the single path; don't branch If how-to bleeds in → agent introduces alternatives that break the learning path explanation Read for context; never execute; never cite as binding fact If reference bleeds in → agent ignores nuance and over-commits to hedged statements Retention by Type (Non-Destructive Scaling) Different types have different lifecycles. Retention policy is type-aware — never apply uniform time-based compression.

Type Lifecycle Retention Policy Reference Persists until superseded Update in place; superseded files get status: superseded How-to Persists until procedure changes Update in place Explanation Persists and grows as understanding deepens Append or revise Tutorial Persists until the product changes enough to invalidate it Rewrite or retire Logs / Activity Temporal — decays Summarise on a schedule; raw content archived or deleted Derived / Computed Regenerable Keep the latest generation; discard prior if regenerable Workflow — Iterative Improvement Diátaxis is a guide, not a plan. Don't restructure everything at once. Don't create empty folder structures. Instead:

Choose something — any file, the one in front of you right now. Assess it — what user need does it serve? How well? Does it blur types? Decide — what single action will produce an immediate improvement? Do it — complete it, publish it, move on. Repeat. Let structure emerge from improved content, not the other way round. A plant is never finished but always complete at every stage of growth.

Do Not Create four empty type folders with nothing in them. That is horrible. Structure should emerge from good content, not precede it.

Based on Diátaxis by Daniele Procida (diataxis.fr). This document is a reference distillation for vault use. Generated for integration into Obsidian-based knowledge systems with agentic consumption.