Скил diataxis-docs — четыре категории без исключений
Как скил diataxis-docs применяет таксономию Diátaxis ко всем репозиториям под управлением Datarim, сопоставляя каждый тип документации с одной из четырёх ортогональных категорий и блокируя антипаттерны, разрушающие структуру со временем.
Документация имеет свойство обрастать отдельной категорией для каждого типа контента: страница FAQ, страница примеров, страница разбора ошибок и в конечном счёте страница для всего, что не вписывается никуда. Скил diataxis-docs реализует другой подход: четыре категории, каждая определена намерением читателя, и закрытое соответствие, которое относит каждый тип документации ровно к одной из них.
Четыре категории
Туториалы — для обучения. Читатель — новичок, который пока не знает, какие задавать вопросы, и нуждается в пошаговом руководстве, чтобы получить базовые знания. How-to руководства — для решения задач: читатель знает, что хочет сделать, и ищет точные инструкции для выполнения конкретного действия. Справочные материалы — для поиска: сигнатуры API, ключи конфигурации, флаги команд, точные значения параметров. Объяснение — для понимания: проектные решения, архитектурные компромиссы и концептуальный фон, помогающий читателю выстроить ментальную модель того, почему система работает именно так.
Различие между справочником и объяснением — частый источник путаницы. Архитектурный контент может попасть в любую из двух категорий. Если читатель ищет факты о структуре системы — это справочник. Если читатель ищет понимание обоснования этой структуры — это объяснение. Скил делает этот выбор явным через таблицу соответствий.
Структура репозитория
Каждый новый репозиторий, созданный в рамках Datarim, получает директорию docs/ с четырьмя поддиректориями: tutorials/, how-to/, reference/ и explanation/. Каждая содержит заглушку README.md. Опциональная директория ephemeral/ хранит временные рабочие материалы — планы, исследовательские заметки, ревью — которые не являются документацией и не нуждаются в категории Diátaxis. Инициализация идемпотентна: директории и файлы создаются только если их ещё нет.
Скил стекоагностичен по замыслу. Он не называет никакого генератора статических сайтов и никакой CMS. Таксономия — это мандат; выбор инструментов принадлежит каждому проекту отдельно.
Антипаттерны, которые блокирует скил
В скиле перечислены шесть конкретных антипаттернов. Один из них — FAQ как пятая категория: записи FAQ — это либо how-to (пошаговые инструкции), либо объяснение (контекст), и правильное решение — разделить их, а не добавлять категорию. Другой — примеры как пятая категория: примеры, ориентированные на задачу, относятся к how-to, каталогизированные примеры — к справочнику. Третий — отношение ко всему архитектурному контенту как к справочнику: контент с объяснением проектных решений относится к категории объяснения.
Детектор дрейфа в шаге 6 команды /dr-optimize проверяет наличие всех четырёх директорий и хотя бы трёх документационных файлов. Проверка мягкая — выдаёт предупреждение, но не блокирует сборки. Жёсткий CI-гейт занесён в беклог для активации после того, как мандат достигнет не менее трёх живых потребителей.
Исключения
От мандата освобождены репозитории только для исследований, репозитории только для архивов, хранилища Obsidian со структурой PARA и унаследованные репозитории, созданные до даты мягкого утверждения мандата. Оператор также может пометить любой репозиторий как явно исключённый в файле datarim/docs/exemptions.json, что убирает его из детекции дрейфа до отзыва переопределения.
Каноническая спецификация, которую реализует этот скил, — публичный фреймворк Diátaxis на diataxis.fr. Общий контекст проекта — в посте что такое Datarim; место детектора дрейфа в аудиторском рабочем процессе описано в статье о команде /dr-optimize.