SECURITY REVIEW
Not yet assessed
Review the original instructions and requested permissions before installing.
No security review is available for this catalog entry yet.
Community / AGENT SKILL
technical-writing
0
Инженерная документация — структура README, копипастабельные примеры, таблицы vs проза, многоязычный паритет (RU/EN), ADR-формат, Keep a Changelog, стиль без воды. Use при написании/обновлении README, docs/*, CONTRIBUTING, ARCHITECTURE, CHANGELOG, release notes и аудите дрейфа доков.
Understand the trade-offs.
SKILL QUALITY
Not yet assessed
How clearly the skill guides your agent, how complete its workflow is, and how you can check the outcome.
No quality assessment is available for this catalog entry yet.
The full skill.
Original instructions from the publisher’s SKILL.md
# Навык: 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`»); термины/команды — как есть, в бэктиках; без воды (удалил — смысл цел → удаляй); читатель — новичок в проекте, но инженер; пиши для сканирования: заголовки-утверждения, важное — в начале раздела.