audit-docs-structure

Documentation skill

Skill version: 1.2_2026.07.21

Unifies all of IDM's topic-type documentation guidance (borrowed from Diátaxis) into one Skill. Claude activates this Skill whenever documentation is written, reviewed, or improved, and new topics are added within the table of contents. It then "lazy loads" the exact documentation type guidance by opening the reference docs linked below.

IDM's guidance borrows heavily from the Diátaxis framework but diverges on TOC organization: tutorials and reference live at the top level, while how-to and explanation topics are grouped into "user guides" by subject matter (with explanation topics typically as the parent). See references/toc.md for details.

Diátaxis framework by Daniele Procida. See diataxis.fr for full attribution. Framework for the skill and reference file based on the work by thewodapp.

Critical workflow

REQUIRED: Before writing or reviewing ANY documentation, you MUST load the relevant documentation type reference file(s) using the Read tool.

1. Use the compass to identify the documentation type needed (see below)
2. Read the matching reference file(s) BEFORE writing/reviewing:
   • Learning experiences → Read references/tutorials.md
   • Task-oriented how-tos → Read references/howto.md
   • Information lookup → Read references/reference.md
   • Understanding & context → Read references/explanation.md
3. Apply the documentation type's principles from the loaded reference
4. Write or review documentation according to that type's standards
5. Add the topic to the documentation set table of contents and include cross-references → Read references/toc.md

DO NOT attempt to write or review documentation without first loading the appropriate reference file(s).

The Diataxis compass

The compass is your primary decision-making tool. Consider the user's goals and needs, and ask two questions:

Question 1: Action or cognition?