Technical Writing

---
name: technical-writing
description: Инженерная документация — структура README, копипастабельные примеры, таблицы vs проза, многоязычный паритет (RU/EN), ADR-формат, Keep a Changelog, стиль без воды. Use при написании/обновлении README, docs/*, CONTRIBUTING, ARCHITECTURE, CHANGELOG, release notes и аудите дрейфа доков.
---

# Навык: Technical Writing

Ключевой принцип: **врущая документация хуже отсутствующей** — читатель ей верит и теряет часы. Каждый факт проверяем: команды прогоняются, флаги/env грепаются по коду, счётчики/версии читаются из реальных файлов (`package.json`, `ls | wc -l`, `git tag`), не «по памяти».

## Структура README (порядок обязателен)
1. Лид-абзац «что это и зачем» (2–4 предложения, отличие от статус-кво) → 2. Quickstart (минимум шагов до работающего) → 3. Usage (сценарии с рабочими примерами) → 4. Configuration (таблица: параметр → тип → дефолт → назначение, из кода) → 5. Troubleshooting → 6. Contributing/License.
Анти-паттерны: маркетинговая вода («мощный, гибкий»); Quickstart на 15 шагов; примеры «примерно так»; features списком прилагательных; документация будущих возможностей как существующих.

## Пример копипастабелен и работает
Скопировал блок → выполняется без правок; исключение — явные плейсхолдеры `<TOKEN>`. Перед публикацией пример прогоняется (минимум `bash -n` + сверка со `scripts`). Показывай ожидаемый результат (`# → Server listening on :3000`). Один блок — один сценарий.

## Таблицы vs проза
Перечислимое (env, опции CLI, эндпоинты, версии) → таблица: дрейф виден построчно. Причины/компромиссы/«почему» → проза. Шаги — нумерованный список; вложенность >2 уровней — переструктурируй.

## Лид-абзац
Формула: *[Что это] делает [что] для [кого]. В отличие от [статус-кво] — [ключевое отличие].* Не решил «моё/не моё» после лида — лид не работает.

## Многоязычный паритет (RU/EN)
Выбери канон (правится первым), второй — зеркало; правка канона → зеркальная правка перевода **в тот же заход**. Чек-лист: одинаковый набор/порядок секций; совпадают версии/счётчики/таблицы; кодовые блоки идентичны (код не переводится); взаимные ссылки-переключатели вверху. Аудит: diff заголовков (`grep '^#' a.md b.md`) + сверка кодовых блоков.

## ADR (кратко)
Для ключевых решений: `Context` (проблема/ограничения) / `Decision` (что выбрали, что отвергли — по строке) / `Consequences` (чем платим, что получаем). Три поля, без эпоса.

## Keep a Changelog
Секции в порядке: Added / Changed / Deprecated / Removed / Fixed / Security (пустые опускаются); `## [Unreleased]` сверху, ниже `## [X.Y.Z] — YYYY-MM-DD` (SemVer). Breaking — первыми, с миграцией. Запись — для пользователя релиза, не пересказ коммита; источник — git-история и diff.

## Стиль
Активный залог, вторая форма («запусти `npm test`»); термины/команды — как есть, в бэктиках; без воды (удалил — смысл цел → удаляй); читатель — новичок в проекте, но инженер; пиши для сканирования: заголовки-утверждения, важное — в начале раздела.