jtprogru 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. Покажи и спроси
Покажи финальный скелет с заполненными шагами. Спроси:
- Принять
- Расширить какой-то шаг (нужны детали)
- Сжать (туториал получился длинным)
- Добавить раздел (security, production-readiness, alternatives)
Чего не делать
- не пиши туториал на сценарий, который сам ни разу не проходил — даже частично выдуманные команды убивают доверие
- не объясняй основы стека внутри туториала — линкуй внешние доки
- не делай «всё в одной статье» — туториал на 50+ минут лучше разбить
- не пиши команды с placeholder'ами вроде
<your-cluster>без объяснения - не пропускай раздел проверки — это то, что отличает туториал от блог-поста