content-documentation · diff
git:20260808.e616f6d to git:20260809.f4a62e7
146 added, 0 removed. Audit C to A.
+ ---
+ name: content-documentation
+ description: >
+ Структурирует технический туториал — prerequisites, цель «после прочтения сможешь
+ X», нумерованные шаги с командами и проверками, troubleshooting, cleanup. Не
+ пишет полный текст: создаёт корректный скелет, в который автор досыпает детали.
+ Используй, когда «написать туториал», «оформить пошаговую инструкцию», «how-to»,
+ «tutorial»,«гайд по развёртыванию», «инструкция, как сделать X».
+ ---
+ # content-documentation — Скелет технической документации
+
+ Цель: дать читателю **повторяемый** путь от исходного состояния к цели. Не теория, не эссе — пошаговая инструкция, где каждый шаг проверяем.
+
+ Перед началом прочитай:
+ - `~/.claude/rules/content-voice.md`
+ - `~/.claude/rules/content-formatting.md` — раздел про туториалы
+ - `~/.claude/rules/sre-runbook-template.md` — стиль исполняемых процедур (туториал близок к runbook'у по принципам команд)
+
+ ## Шаг 1. Определи scope
+
+ Спроси:
+ - **цель туториала**: «после прочтения читатель сможет _<глагол + результат>_»
+ - примеры: «развернуть Postgres-кластер с replication на 3 нодах», «настроить OAuth-логин через Google в Express-приложении», «измерить heap-аллокации в Go-сервисе»
+ - **исходное состояние читателя**: что у него есть, что предполагается
+ - **финальное состояние**: что должно работать в конце
+ - **платформа / стек**: версии, ОС, облако
+
+ Если цель размытая («туториал по k8s») — **остановись и помоги вычленить конкретику**. Туториал «по k8s» невозможен — возможен «развернуть minikube + deploy stateless API + expose via Ingress».
+
+ ## Шаг 2. Сложи скелет
+
+ ```markdown
+ # <Название: глагол + результат>
+
+ > **Цель:** после прохождения туториала ты сможешь _<конкретно>_.
+ > **Время:** ~X минут.
+ > **Уровень:** новичок / средний / продвинутый.
+
+ ## Что понадобится
+
+ - <тулинг: версия>
+ - <тулинг: версия>
+ - <доступ: где взять>
+ - <облако/окружение, если применимо>
+
+ ## Шаг 1. <Глагол + что>
+
+ <1-2 строки контекста: что делаем и зачем.>
+
+ ```<lang>
+ <команда>
+ ```
+
+ **Проверка:** <ожидаемый результат / команда, подтверждающая успех>
+
+ ## Шаг 2. <Глагол + что>
+
+ ...
+
+ ## Шаг N. <Глагол + что>
+
+ ...
+
+ ## Проверка финального состояния
+
+ <команда или сценарий, который проверяет, что всё работает end-to-end>
+
+ ## Troubleshooting
+
+ ### <Симптом 1>
+
+ **Причина:** ...
+ **Решение:** ...
+
+ ### <Симптом 2>
+
+ ...
+
+ ## Cleanup
+
+ <команды, чтобы откатить всё созданное — если читатель не хочет оставлять>
+
+ ## Что дальше
+
+ <2-3 ссылки: углубление темы, related туториалы, доки>
+ ```
+
+ ## Шаг 3. Согласуй скелет
+
+ Покажи пользователю **только структуру** (заголовки шагов и краткое описание каждого), без полного текста. Спроси:
+ - все ли шаги нужны?
+ - ничего не пропущено между шагами?
+ - порядок логичный?
+
+ После подтверждения — переходи к заполнению.
+
+ ## Шаг 4. Заполни шаги
+
+ Для каждого шага:
+
+ - **Глагол первым** в заголовке: «Установи kubectl», «Создай namespace», «Проверь подключение»
+ - **Контекст** — почему делаем (1-2 строки, не лекция)
+ - **Команда(ы)** в code block с языком, **готовые к копипасту** (см. `sre-runbook-template.md`)
+ - **Проверка** — команда или ожидаемый вывод, чтобы читатель убедился, что шаг прошёл
+
+ Каждый параметр, который читатель должен заменить — объясни **где его взять**:
+ ```bash
+ kubectl apply -f deploy.yaml -n <namespace>
+ # <namespace> — имя из шага 2, например "demo-app"
+ ```
+
+ ## Шаг 5. Troubleshooting
+
+ 3-5 типичных проблем, с которыми сталкиваются. Для каждой:
+ - **симптом** (как читатель увидит)
+ - **причина** (почему случилось)
+ - **решение** (что сделать)
+
+ Не пиши troubleshooting на гипотетические проблемы — только на те, которые реально случались.
+
+ ## Шаг 6. Cleanup
+
+ Команды, чтобы откатить созданное. Это важно — без cleanup читатель боится экспериментировать.
+
+ ## Шаг 7. Самопроверка
+
+ - **прошёл ли** ты туториал глазами впервые? Каждый шаг ясен без контекста статьи?
+ - **команды копипастабельны**? Нет ли `<your-thing>` без объяснения?
+ - **версии указаны**? Через 6 месяцев туториал не должен ломаться от того, что вышел новый minor.
+ - **проверки после каждого шага**? Иначе читатель не знает, где ошибся.
+
+ ## Шаг 8. Покажи и спроси
+
+ Покажи финальный скелет с заполненными шагами. Спроси:
+ 1. Принять
+ 2. Расширить какой-то шаг (нужны детали)
+ 3. Сжать (туториал получился длинным)
+ 4. Добавить раздел (security, production-readiness, alternatives)
+
+ ## Чего не делать
+
+ - не пиши туториал на сценарий, который сам ни разу не проходил — даже частично выдуманные команды убивают доверие
+ - не объясняй основы стека внутри туториала — линкуй внешние доки
+ - не делай «всё в одной статье» — туториал на 50+ минут лучше разбить
+ - не пиши команды с placeholder'ами вроде `<your-cluster>` без объяснения
+ - не пропускай раздел проверки — это то, что отличает туториал от блог-поста