diataxis

SKILL.md

---
name: diataxis
description: Помогает поддерживать страницы документации на основе метода Diataxis. Анализирует существующую документацию, классифицирует страницы по категориям: учебники, инструкции, объяснения, справочники, выявляет пробелы и помогает создавать или перестраивать документацию в соответствии с принципами Diataxis. Используйте, когда пользователь упоминает структуру документации, Diataxis, категории документации, учебники против инструкций или реорганизацию документации.
---

# Поддержка документации с помощью метода Diataxis

Вы помогаете пользователю организовать и поддерживать документацию проекта в соответствии с фреймворком Diataxis.

## Что такое Diataxis?

Diataxis (от древнегреческого: *dia* — «через», *taxis* — «расположение») — системный подход к технической документации, который организует контент в четыре категории на основе потребностей пользователя. Полный фреймворк смотрите на [diataxis.fr](https://diataxis.fr/).

| Категория         | Ориентация            | Цель                                     | Форма               |
| ----------------- | --------------------- | ---------------------------------------- | ------------------- |
| **Учебники**      | Ориентация на обучение | Помочь новичку пройти обучение           | Урок                |
| **Руководства**   | Ориентация на задачу   | Помочь выполнить конкретную задачу       | Серия шагов         |
| **Объяснения**    | Ориентация на понимание| Углубить понимание через обсуждение      | Рассуждение         |
| **Справочник**    | Ориентация на информацию| Предоставить точные технические описания | Сухие, точные факты |

### Компас — две оси для классификации

Используйте два вопроса для классификации любого контента (см. [references/compass.md](references/compass.md)):

|                   | Приобретение (изучение) | Применение (работа) |
| ----------------- | ----------------------- | ------------------- |
| **Действие** (практика) | Учебник                 | Руководство         |
| **Познание** (теория)    | Объяснение              | Справочник          |

1. **«Это про действие или познание?»** — Делает ли читатель что-то или понимает что-то?
2. **«Это про приобретение или применение?»** — Изучает ли читатель или работает?

### Ключевые различия

- **Учебники vs Руководства**: Учебники обучают («следуй за мной») для учеников; руководства направляют («сделай так») для практиков. Учебники полные, от начала до конца; руководства начинаются и заканчиваются в разумных точках, чтобы читатель мог присоединить их к своей работе.
- **Объяснения vs Справочник**: Объяснения обсуждают почему (рассуждения, допускают мнение); справочник сообщает что (строго, авторитетно, без двусмысленностей).
- **Действие vs Познание**: Учебники и руководства практические (делание). Объяснения и справочник теоретические (знание).
- **Приобретение vs Применение**: Учебники и объяснения служат обучению/изучению. Руководства и справочник служат работе/кодированию.

## Шаг 1: Обнаружение существующей документации

1. **Просмотрите проект на наличие файлов документации:**
   - Ищите каталоги `docs/`, `doc/`, `documentation/`
   - Проверьте наличие markdown-файлов в корне проекта: `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`
   - Ищите другие форматы документации: `.rst`, `.adoc`, `.txt`
   - Проверьте конфигурацию документации: `mkdocs.yml`, `docusaurus.config.js`, `conf.py`, `antora.yml`, `hugo.toml`

2. **Прочитайте существующую документацию**, чтобы понять, что уже покрыто.

3. **Если документации нет:**
   - Сообщите пользователю: «Документация не найдена. Давайте создадим структуру документации с нуля.»
   - Перейдите к [Шагу 3: Предложить структуру документации](#step-3-propose-documentation-structure)

## Шаг 2: Классификация существующей документации

Проанализируйте каждую страницу документации и классифицируйте её в одну из четырёх категорий Diataxis.

### Уважайте предыдущие решения по классификации

Перед предложением переклассификации проверьте историю git на предмет преднамеренных перемещений:

```bash
git log --all --oneline --diff-filter=R -- 'docs/**/*.md'
```

Если файл был намеренно перемещён между категориями (например, сообщение коммита
`docs(diataxis): reclassify X as reference`), **уважайте это решение**, если только пользователь
не попросит пересмотреть его. Преднамеренная переклассификация отражает суждение,
которое компас может не охватить — отметьте это пользователю, а не переопределяйте.

### Правила классификации

Используйте вопросы компаса и следующие сигналы. Для подробных рекомендаций по написанию для каждой категории смотрите справочные файлы в `references/`.

**Страница является Учебником, если она** (см. [references/tutorials.md](references/tutorials.md)):

- Ведёт новичка через полный опыт обучения под руководством автора
- Имеет чёткую точку начала и конечную цель, давая видимые результаты на каждом шаге
- Использует первое лицо множественного числа: «В этом учебнике мы...», «Сначала сделайте x. Теперь сделайте y.»
- Следует последовательному повествованию, где читатель учится, делая
- Сфокусирована на приобретении знаний, а не на выполнении реальной задачи
- Минимизирует объяснения — ссылается вместо отвлечения

**Страница является Руководством, если она** (см. [references/how-to-guides.md](references/how-to-guides.md)):

- Ориентирована на конкретную, чёткую цель с точки зрения пользователя (не инструмента)
- Предполагает, что читатель уже имеет базовые знания и знает, чего хочет
- Использует точные заголовки: «Как интегрировать мониторинг», а не «Мониторинг»
- Предоставляет исполнимое решение: «если столкнулись с этой ситуацией, следуйте этим шагам»
- Начинается и заканчивается в разумных точках — читатель присоединяет её к своей работе
- Остаётся практичной без обучения концепциям или включения справочных таблиц

**Страница является Объяснением, если она** (см. [references/explanation.md](references/explanation.md)):

- Обсуждает концепции, фон, проектные решения или компромиссы
- Отвечает на вопрос «Расскажите мне о...» — заголовки работают с неявным префиксом «О»
- Устанавливает связи между концепциями и даёт контекст (история, причины, альтернативы)
- Использует рассуждающий стиль, допускающий мнение и взвешивание разных точек зрения
- Может быть полезна для чтения вне рабочего места
- Сопротивляется восприятию как инструкция или справочный материал

**Страница является Справочником, если она** (см. [references/reference.md](references/reference.md)):

- Описывает API, конфигурации, флаги CLI или структуры данных авторитетно
- Структурирован для поиска (консультируются, а не читаются целиком)
- Сдержан, фактичен и точен — излагает факты декларативным языком
- Отражает структуру описываемого механизма
- Использует последовательные, стандартные шаблоны во всех записях
- Приводит минимальные примеры, демонстрирующие использование без обучения

### Смешанный контент

Многие страницы содержат контент из нескольких категорий. Отметьте их для пользователя и предложите, как их разделить:

- «Эта страница смешивает учебный контент (раздел для начинающих) с справочным контентом
  (таблица API). Рассмотрите возможность разделения на учебную и справочную страницу.»

### Пограничные случаи

Некоторые типы контента находятся на границе компаса. Не применяйте компас механически —
учитывайте **структуру и предполагаемое использование** страницы:

- **Устранение неполадок**: Таблица симптомов, причин и решений — это **Справочник**
  (структурирована для консультации, отражает структуру проблемы, сдержанные факты). Страница,
  которая пошагово ведет через диагностический процесс, — это **Как сделать** (ориентирована на цель).
  Формат определяет категорию, а не предмет.
- **Страницы FAQ**: Отдельные вопросы и ответы часто являются **Справочником** (для поиска).
  Курируемый FAQ, который формирует понимание, — это **Объяснение**.
- **Руководства по миграции**: Пошаговые инструкции по обновлению — это **Как сделать**.
  Обсуждение изменений и причин — это **Объяснение**.

В случае сомнений по пограничному случаю подумайте: *как читатель будет использовать эту страницу?*
Консультация для поиска → Справочник. Следование шагам → Как сделать.

### Представление результатов классификации

Представьте результаты в виде таблицы:

```text
| Файл                    | Текущая категория | Предлагаемая категория | Примечания                    |
|-------------------------|-------------------|------------------------|------------------------------|
| docs/getting-started.md | -                 | Tutorial               | Хорошая структура учебника   |
| docs/api.md             | -                 | Reference              | Содержит некоторый how-to контент |
| docs/architecture.md    | -                 | Explanation            | Хорошо структурированное объяснение |
```

## Шаг 3: Предложить структуру документации

На основе анализа предложите структуру каталогов, соответствующую Diataxis.

### Стандартная структура каталогов

```text
docs/
  tutorials/           # Ориентировано на обучение
    getting-started.md
    first-project.md
  how-to/              # Ориентировано на задачи
    install.md
    configure.md
    deploy.md
  explanation/         # Ориентировано на понимание
    architecture.md
    design-decisions.md
  reference/           # Ориентировано на информацию
    api.md
    configuration.md
    cli.md
```

### Правила адаптации

- **Адаптировать под существующие инструменты**: Если проект использует mkdocs, docusaurus, antora, hugo или подобные,
  предложите структуру, совместимую с конвенциями этого инструмента.
- **Адаптировать под существующую структуру**: Если в проекте уже есть структура docs, частично соответствующая Diataxis,
  предложите минимальные изменения для полного соответствия, а не полную перестройку.
- **Сохранять то, что работает**: Не предлагайте перемещать контент, который уже хорошо классифицирован.
- **Уважать конвенции проекта**: Если проект использует определённый стиль именования
  (kebab-case, snake_case и т.п.), следуйте ему.

### Выявление пробелов в документации

После классификации существующего контента определите отсутствующие части:

- **Нет учебников?** Предложите создать учебник для начинающих.
- **Нет руководств how-to?** Предложите руководства по самым распространённым задачам (установка, настройка, развертывание).
- **Нет объяснений?** Предложите документы по архитектуре или решениям по дизайну.
- **Нет справочника?** Предложите страницы справочника по API, конфигурации или CLI.

Чётко представьте пробелы:

```text
Обнаружены пробелы в документации:
- [ ] Отсутствует: Учебник для начинающих
- [ ] Отсутствует: Руководство how-to по развертыванию
- [ ] Отсутствует: Справочник по параметрам конфигурации
- [x] Есть: Объяснение архитектуры
```

## Шаг 4: Выполнение изменений

**Всегда спрашивайте пользователя перед внесением изменений.** Представьте план и дождитесь одобрения.

### При реструктуризации

1. Представьте предлагаемые перемещения и переименования файлов
2. Дождитесь одобрения пользователя
3. Переместите файлы в новые места
4. Обновите внутренние ссылки между страницами документации
5. Обновите конфигурацию навигации (mkdocs.yml, sidebar config и т.п.), если применимо
6. Проверьте отсутствие битых ссылок

### При создании новых страниц

1. Представьте, какие страницы предлагаете создать
2. Дождитесь одобрения пользователя
3. Создайте страницы с правильной структурой для их категории:

**Шаблон учебника** (см. [references/tutorials.md](references/tutorials.md) для принципов написания):

```markdown
# [Заголовок — укажите, что мы будем создавать]

В этом учебнике мы [конкретная цель — что читатель получит в итоге].

## Перед началом

- [Требование 1]

## Шаг 1: [Первый шаг — конкретное действие]

[Прямое указание. Покажите ожидаемый вывод после каждого шага.]

Вывод должен выглядеть примерно так:

    [пример вывода]

## Шаг 2: [Второй шаг — строится на предыдущем]

[Прямое указание. Обратите внимание на важные моменты.]

Обратите внимание, что [наблюдение, завершающее цикл обучения].

## Что вы создали

Вы создали [конкретное резюме достижения].

## Следующие шаги

- [Ссылка на следующий учебник или связанное руководство how-to]
```

**Шаблон руководства how-to** (см. [references/how-to-guides.md](references/how-to-guides.md) для принципов написания):

```markdown
# Как [достичь конкретной цели]

Это руководство показывает, как [описание задачи].

## Требования

- [Требование — предполагается базовая компетенция]

## Шаги

### 1. [Первый шаг]

[Краткая, практическая инструкция]

### 2. [Второй шаг]

[Краткая, практическая инструкция]

Обратитесь к [x справочнику](link) для полного списка опций.

## Устранение неполадок

### [Распространённая проблема]

Если вы хотите [x], сделайте [y].
```

**Шаблон объяснения** (см. [references/explanation.md](references/explanation.md) для принципов написания):

```markdown
# [Тема — должна читаться естественно после «О»]

[Вводный абзац, который устанавливает контекст и рамки]

## Предыстория

[Исторический контекст, проектные решения или базовые концепции]

## [Основная концепция]

[Развернутое объяснение — установление связей, предоставление контекста, признание точки зрения]

Причина [x] заключается в том, что [исторический/технический контекст].
[W] лучше, чем [z], потому что [обоснование].

## Альтернативы и компромиссы

[Обсуждение других подходов и почему был выбран именно этот]

## Дополнительная литература

- [Связанные ресурсы]
```

**Шаблон справочника** (см. [references/reference.md](references/reference.md) для принципов написания):

```markdown
# [Компонент] Справочник

[Однострочное описание того, что охватывает этот справочник]

## [Раздел — повторяет структуру механизма]

| Параметр | Тип    | По умолчанию | Описание    |
| -------- | ------ | ------------ | ----------- |
| `name`   | string | -            | Описание    |

## [API/Функция/Команда]

**Сигнатура:** `function_name(param1, param2)`

**Параметры:**

- `param1` (тип) — Описание
- `param2` (тип) — Описание

**Возвращает:** Описание возвращаемого значения

**Пример:**

    result = function_name("value", 42)
```

1. Заполните содержимое на основе анализа проекта (исходный код, существующая документация, конфигурационные файлы)

### При улучшении существующих страниц

Если страница уже находится в правильной категории, но нуждается в улучшении для лучшего соответствия принципам Diataxis:

1. Определите конкретные проблемы (смешанный контент, неправильный тон, отсутствующая структура)
2. Представьте пользователю предложенные изменения
3. Внесите изменения после одобрения

## Важные рекомендации

- **Не навязывайте структуру**: Если проект небольшой и один README хорошо покрывает всё,
  скажите об этом. Diataxis наиболее ценен для проектов с обширной документацией.
- **Будьте прагматичны**: Частично организованный набор документации лучше, чем её отсутствие.
  Предлагайте постепенные улучшения, а не требуйте совершенства.
- **Сохраняйте содержимое**: При реструктуризации никогда не удаляйте информацию. Перемещайте и реорганизуйте,
  но сохраняйте все существующие данные.
- **Поддерживайте ссылки**: При перемещении файлов обновляйте все перекрестные ссылки и навигационные настройки.
- **Уважайте решения пользователя**: Если пользователь не согласен с классификацией или предложением по реструктуризации,
  примите его решение и подстройтесь под него.
- **Осознавайте качество**: Diataxis способствует качеству, но не гарантирует его — точность,
  полнота и хорошее письмо остаются ответственностью автора. См. [references/quality.md](references/quality.md) для измерений качества.
- **Используйте компас при сомнениях**: Если классификация неясна или написание даётся с трудом,
  применяйте два вопроса компаса. См. [references/compass.md](references/compass.md).

## Справочные документы

Подробные рекомендации по написанию для каждой категории, взятые с [diataxis.fr](https://diataxis.fr/):

- [references/tutorials.md](references/tutorials.md) — Педагогические принципы, языковые конвенции, антипаттерны
- [references/how-to-guides.md](references/how-to-guides.md) — Принципы написания, охват, отличие от учебников
- [references/explanation.md](references/explanation.md) — Характеристики, области обсуждения, тест на название
- [references/reference.md](references/reference.md) — Принципы строгости, зеркальная структура, примеры
- [references/compass.md](references/compass.md) — Инструмент принятия решений по двум осям для классификации
- [references/quality.md](references/quality.md) — Функциональные и глубокие измерения качества