content-tutorial-structure — Скелет технического туториала

Цель: дать читателю повторяемый путь от исходного состояния к цели. Не теория, не эссе — пошаговая инструкция, где каждый шаг проверяем.

Перед началом прочитай:

• ../../rules/content-voice.md
• ../../rules/content-formatting.md — раздел про туториалы
• ../../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. Сложи скелет

# <Название: глагол + результат>

> **Цель:** после прохождения туториала ты сможешь _<конкретно>_.
> **Время:** ~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> без объяснения
• не пропускай раздел проверки — это то, что отличает туториал от блог-поста