mcpField
D
diataxis-organize-docs

diataxis-organize-docs

github.com/trogonstackDocuments1161 installsUpdated 2d ago
Repository

About diataxis-organize-docs

diataxis-organize-docs is a skill for organizing documentation using the Diátaxis categories. It guides documentation maintainers through classification, hierarchy planning, document splitting, navigation, and verification.

Key features

  1. 01Classify content into four categories
  2. 02Plan documentation hierarchies
  3. 03Split documents with mixed purposes
  4. 04Build documentation navigation
  5. 05Check links and content completeness

Use cases

  1. 01Reorganize an existing documentation set
  2. 02Plan a new documentation structure
  3. 03Split documents mixing tutorials and reference
  4. 04Review documentation navigation and links

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/trogonstack/agentskills --skill diataxis-organize-docs

After installing, type/diataxis-organize-docsin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
classification.md
navigation.md
splitting.md

Details

From the project README

Diataxis Documentation Organization

Reorganize documentation by classifying content into the Diataxis categories and creating a structured documentation hierarchy.

Documentation Categories

QuadrantOrientationPurposeUser Need
TutorialLearningTeach through doing"I want to learn"
How-toTaskSolve specific problems"I want to accomplish X"
ReferenceInformationDescribe the machinery"I need facts about Y"
ExplanationUnderstandingClarify concepts"I want to understand why"

Directory Structure

Organize docs into this hierarchy, adding topic subdirectories as needed:

docs/
├── tutorial/            # Learning-oriented
│   ├── getting-started/
│   └── {topic}/
├── how-to/              # Task-oriented
│   ├── {task-category}/
│   └── troubleshooting/
├── reference/           # Information-oriented
│   ├── api/
│   ├── configuration/
│   └── architecture/
├── explanation/         # Understanding-oriented
│   ├── concepts/
│   ├── decisions/
│   └── background/
└── README.md            # Navigation hub

Always use docs/README.md as the root navigation file, never index.md.

Writing Conventions

Keep skill instructions and generated documentation free of manually maintained totals and numbered section references. Use descriptive headings and named links. For ordered procedures, write each Markdown list marker as 1. so the renderer maintains numbering. Preserve numeric facts that are necessary to understand or use the subject.

Workflow

Load only the references needed for the current task:

  1. Analyze existing content. Classify each file or section by the reader's need. Read classification criteria when classifying existing content or resolving ambiguous categories.
  2. Map the structure. Assign content to the hierarchy above and identify which documents to keep, move, or split.
  3. Separate mixed documents. When a document serves multiple purposes, read splitting guidance for the migration procedure and example. Preserve context and link related content across quadrants.
  4. Build navigation. When creating or updating the documentation hub, read navigation guidance for its template. Update links affected by moved or split content.
  5. Verify and report. Apply the completion checks below. For an audit, report the current state, classifications, proposed file placements, and needed cross-references. For completed edits, summarize the changes and verification. Scale the report to the task.

Completion Checks

  • Each document serves one purpose
  • Tutorials have clear learning outcomes
  • How-to guides solve specific problems
  • Reference is complete and accurate
  • Explanations provide genuine insight
  • Cross-references connect related content and resolve after moves
  • docs/README.md makes user intent clear
  • No orphaned, duplicated, or lost content

Comments

Markdown supported