Technical Writing

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

# Навык: Technical Writing

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

## 1. Структура README (порядок обязателен)
| # | Раздел | Что внутри | Обязателен |
|---|---|---|---|
| 1 | Лид-абзац | «Что это и зачем» в 2–4 предложениях; чем отличается от аналогов | да |
| 2 | Quickstart | Минимум шагов до работающего результата (install → run → увидеть) | да |
| 3 | Usage | Основные сценарии, каждый — с рабочим примером | да |
| 4 | Configuration | Таблица: параметр/env → тип → дефолт → назначение (из кода) | если есть конфиг |
| 5 | Troubleshooting | Реальные частые ошибки → причина → фикс | желателен |
| 6 | Contributing / License | Ссылка на CONTRIBUTING.md; лицензия | да |

Анти-паттерны: маркетинговая вода в лиде («мощный, гибкий, современный»); Quickstart на 15 шагов; примеры «примерно так»; скриншоты вместо копируемого текста команд; раздел Features списком прилагательных без примеров; документация будущих возможностей как существующих.

## 2. Пример копипастабелен и работает
- Читатель копирует блок → блок выполняется без правок. Единственное исключение — явные плейсхолдеры в угловых скобках: `<TOKEN>`, `<DB_URL>`.
- Перед публикацией пример **прогоняется** (или как минимум `bash -n` + сверка команды со `scripts` в `package.json`).
- Показывай и ожидаемый результат: `# → Server listening on :3000` — читатель должен понять, что «получилось».
- Один блок — один сценарий; не смешивай setup и usage в одной простыне.

## 3. Таблицы для перечислимого, проза для объяснений
- Перечислимое (env-переменные, опции CLI, эндпоинты, поддерживаемые версии) → **таблица**: сканируется глазами, дрейф виден построчно.
- Причины, компромиссы, «почему так» → **проза**: таблица не объясняет.
- Списки — для шагов (нумерованный) и коротких наборов (маркированный); вложенность глубже двух уровней — сигнал переструктурировать.

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

## 5. Многоязычный паритет (RU/EN)
1. Выбери **канон** — язык, на котором доки правятся первыми (обычно EN для публичного, RU для внутреннего). Второй язык — зеркало, помечен как перевод.
2. Правка канона и синхронизация перевода — **в один заход**, не «потом».
3. Чек-лист синхронизации: одинаковый набор и порядок секций; совпадают версии, счётчики, таблицы опций; блоки команд/кода идентичны байт-в-байт (код не переводится); взаимные ссылки-переключатели вверху (`[EN](README.md) | [RU](README.ru.md)`).
4. Аудит паритета: diff по заголовкам (`grep '^#' a.md b.md`) + сверка кодовых блоков.

## 6. ADR — фиксация решений (кратко)
Для ключевых архитектурных решений (в `ARCHITECTURE.md` или `docs/adr/NNNN-*.md`):
```
## <Решение одной строкой>
- Context: какая проблема/ограничения стояли
- Decision: что выбрали (и что отвергли)
- Consequences: чем платим и что получаем
```
Три поля, без эпоса. Отвергнутые альтернативы — одна строка каждая: они экономят будущие споры.

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

## 8. Стиль
- **Активный залог, вторая форма**: «запусти `npm test`», а не «тесты могут быть запущены».
- Термины, имена файлов, команды, коды — как есть, в бэктиках; не переводи `pull request` как «запрос на слияние» в инженерной доке.
- Без воды: удали слово/абзац — смысл не пострадал → удаляй. Прилагательные («мощный», «удобный») не несут фактов.
- Читатель — новичок в проекте, но инженер: не объясняй, что такое git; объясняй, как устроен ЭТОТ проект.
- Пиши для сканирования: заголовки-утверждения, короткие абзацы, важное — в начале раздела.