understand-doc-system

Plan software documentation using the four-quadrant Diataxis documentation framework.

2.4k|148|Updated Mar 11, 2019
One-click install
npx skills add https://github.com/siriwatknp/mui-treasury --skill understand-doc-system
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: understand-doc-system
Source: https://github.com/siriwatknp/mui-treasury/tree/main/.claude/skills/understand-doc-system
Command: npx skills add https://github.com/siriwatknp/mui-treasury --skill understand-doc-system

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Most documentation fails because authors mix tutorials, how-to guides, reference material, and explanation into one undifferentiated mass. This Skill provides a structured framework for understanding the four distinct functions of documentation before writing, so each piece of content serves exactly one purpose.

Core Features & Use Cases

  • Four-Quadrant Framework: Explains the Diataxis documentation system dividing content into tutorials, how-to guides, technical reference, and explanation.
  • Writing Guidelines per Quadrant: Detailed pages describe how to write each documentation type, including structure, tone, and common pitfalls.
  • Documentation Analysis: Use the framework to audit existing documentation and identify which quadrant each piece belongs to or is missing.
  • Use Case: Before writing docs for a new open-source library, invoke this Skill to plan a documentation structure with a beginner tutorial, task-oriented how-to guides, API reference, and conceptual explanation sections.

Quick Start

Help me plan the documentation structure for my project using the four-quadrant documentation system.

Frequently Asked Questions about understand-doc-system

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is the Diataxis documentation framework?

Diataxis is a documentation system that divides content into four types: tutorials, how-to guides, technical reference, and explanation. Each type serves a distinct user need and requires a different writing approach, and they must be kept separate.

How do I structure documentation for a software project?

Structure documentation around four quadrants: learning-oriented tutorials for beginners, goal-oriented how-to guides for specific tasks, information-oriented reference describing the machinery, and understanding-oriented explanation for context and background.

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

A tutorial is a learning-oriented lesson where the author decides what a beginner needs to do. A how-to guide is goal-oriented, answering a specific question from a user who already has some experience and knows what they want to achieve.

When should I write explanation documentation instead of reference?

Write explanation when providing background, context, design decisions, or discussion of alternatives. Reference documentation only describes the machinery such as classes, functions, and APIs, and should not contain discussion or instruction.

Why does mixing documentation types cause problems?

Each documentation type has a different purpose and writing mode, so mixing them pulls content in conflicting directions. Documentation that fails to keep the four quadrants separate becomes harder to write, maintain, and navigate.