Skip to content

Diátaxis framework adoption in DSOM

An architectural overview explaining the adoption, structure, and benefits of the Diátaxis documentation framework in the DSOM project.

What is Diátaxis?

The Diátaxis Framework is a systematic approach to technical documentation. It categorises files based on their purpose and user intent, separating content into four distinct quadrants:

               USER INTENT
        Learning        Practical
      +---------------+---------------+
      |   TUTORIALS   | HOW-TO GUIDES |
Acq.  |  (Learning-   |  (Problem-    |
      |   oriented)   |   oriented)   |
      +---------------+---------------+
      |  EXPLANATION  |   REFERENCE   |
Und.  |  (Concept-    |  (Information-|
      |   oriented)   |   oriented)   |
      +---------------+---------------+

Why adopt Diátaxis in DSOM?

Historically, AI agent tool documentation was mixed with procedural runbooks. This led to high cognitive load and excessive token consumption.

Adopting Diátaxis provides three main benefits: - Reduces token costs: Separate reference files allow AI agents to fetch precise factual details without reading conversational or tutorial text. - Speeds up onboarding: Human developers can follow step-by-step lessons without getting bogged down in low-level arguments. - Clarifies purpose: Developers and writers know exactly where a new document belongs based on the user's intent.

Quadrant mappings in DSOM

Our documentation Palace is structured cleanly inside docs/ using the four Diátaxis folders:

  1. Tutorials (docs/tutorials/):
  2. Guided learning lessons for beginners.

  3. Example: Getting Started with DSOM Tools.

  4. How-To Guides (docs/how-to/):

  5. Goal-oriented, step-by-step instructions for specific real-world tasks.

  6. Example: Run the FastMCP Server.

  7. Reference (docs/reference/):

  8. Factual description, API signatures, and configurations for all 8 Python scripts.

  9. Example: apply_okf_frontmatter.py Reference.

  10. Explanation (docs/explanation/):

  11. Context, architecture, and design rationale behind our components.
  12. Example: OpenWiki & FastMCP Architecture.

Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-08-14 Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0