Diátaxis Docs Taxonomy
Мандат на таксономию документации для всех репозиториев и сайтов под управлением Datarim: четыре ортогональные категории (tutorials, how-to, reference, explanation), закрытая таблица маппинга, список исключений, определения анти-паттернов. Загружается /dr-init, /dr-optimize, /dr-archive.
Обзор
Diátaxis Docs Taxonomy — контракт на структуру документации в экосистеме Arcanada. Каждый репозиторий и продуктовый сайт под управлением Datarim обязан организовать документацию ровно в четыре ортогональные категории: tutorials, how-to, reference и explanation. Никакие новые категории верхнего уровня не могут быть введены. Все типы контента, включая FAQ, glossary, troubleshooting, examples и overview, должны быть сопоставлены одной из четырёх канонических категорий. Мандат не зависит от выбора генератора статических сайтов.
Четыре категории
- Tutorials — Обучающая категория для начинающих. Цель читателя: получить фундаментальные знания через пошаговое руководство. Типичный контент: руководства по началу работы, интерактивные уроки, первые приложения.
- How-to — Задачно-ориентированная категория для практиков. Цель читателя: решить конкретную проблему или выполнить задачу. Типичный контент: руководства по развёртыванию, рецепты тестирования, инструкции по отладке.
- Reference — Информационно-ориентированная категория для поиска. Цель читателя: найти точные параметры, сигнатуры API, ключи конфигурации. Типичный контент: API-документация, флаги командной строки, схема конфигурации.
- Explanation — Категория для глубокого понимания. Цель читателя: понять почему что-то работает именно так. Типичный контент: архитектурные обзоры, дизайн-решения, анализ компромиссов.
Структура репозитория
<project-root>/docs/
├── tutorials/
│ └── README.md
├── how-to/
│ ├── README.md
│ ├── testing.md (*)
│ ├── deployment.md (*)
│ └── gotchas.md (*)
├── reference/
│ ├── README.md
│ └── architecture.md (*)
├── explanation/
│ └── README.md
├── ephemeral/ (рабочие материалы)
│ ├── plans/
│ ├── research/
│ └── reviews/(*) — legacy stubs, автоматически сопоставленные из прежней плоской структуры. Идемпотентность: файл или директория создаётся только если не существует.
Таблица сопоставления
| Legacy-тип | Категория Diátaxis | Обоснование |
|---|---|---|
| architecture (default) | reference | Информационно — описание структуры системы |
| architecture (why) | explanation | Понимание — дизайн-решения, компромиссы |
| testing | how-to | Решение задач — как запускать тесты |
| deployment | how-to | Решение задач — как развернуть приложение |
| gotchas | how-to | Решение задач — что делать при типичных ошибках |
| api | reference | Информационно — поиск документации |
| cli | reference | Информационно — сигнатуры команд |
| config | reference | Информационно — схема конфигурации |
| concepts | explanation | Понимание — концептуальная база |
| design | explanation | Понимание — обоснование дизайна |
| tutorial | tutorials | Обучение — первый end-to-end опыт |
| quickstart | tutorials | Обучение — минимальная настройка |
| faq | how-to or explanation | Процедурное в how-to; концептуальное в explanation |
| troubleshooting | how-to | Решение проблем — что делать при сбоях |
| examples | how-to or reference | Примеры с задачами в how-to; каталоги в reference |
| glossary | reference | Информационно — определения |
Это закрытый набор. Никакие новые типы документации не могут быть введены как отдельные категории.
Анти-паттерны
- FAQ как пятая категория. FAQ — конгломерат how-to и explanation. Решение: разделить записи FAQ по категориям с перекрёстными ссылками.
- Examples как пятая категория. Примеры — либо how-to (задачи), либо reference (каталоги). Решение: размещать каждый пример в семантической категории.
- Architecture всегда reference. Контент о дизайн-решениях должен быть в explanation/. Решение: оценить намерение читателя.
- Index-страница как категория. docs/index.md — точка входа, не тип документации. Решение: index — навигация, не контейнер контента.
- Troubleshooting как отдельная категория. Решение: размещать в how-to/ с явными заголовками проблем.
- Межкатегорийный дрейф. Со временем контент накапливает материал других категорий. Решение: при ревью проверять каждый файл на соответствие определению категории.
Список исключений
- Research-only репозитории (без пользовательской документации).
- Archive-only репозитории (снэпшоты, бэкапы, история).
- Obsidian vaults с PARA-структурой.
- Отдельные заметки-файлы или черновики (временные, непубличные).
- Legacy репозитории, созданные до даты утверждения мандата.
- Временные директории (temp/*, scratch/*, test-scaffold/*).
Оператор может явно пометить репозиторий как намеренное исключение в реестре исключений.
Stack-Agnostic Boundary
Мандат НЕ ДОЛЖЕН называть конкретный SSG или CMS (Docusaurus, Mintlify, VitePress, Hugo, Sphinx). Выбор генератора документации — ответственность проекта и лежит вне рамок мандата таксономии.
Slogan Compliance
Каждый обновлённый публичный сайт экосистемы должен отображать слоган на видном месте (footer, header, splash-страница). Соответствие проверяется в /dr-publish workflow и /dr-archive surface scan.
Drift Detection
Соответствие мандату проверяется /dr-optimize Step 6 через filesystem-presence check. Обнаружение мягкое — только предупреждение, не блокировка. Жёсткий CI gate (exit code 1) отложен в INFRA-* backlog до принятия мандата как минимум тремя потребителями.