Content tutorial structure

Skill jtprogru/bear-skills/skills/content-tutorial-structure

Структурирует технический туториал — prerequisites, цель «после прочтения сможешь X», нумерованные шаги с командами и проверками, troubleshooting, cleanup. Не пишет полный текст: создаёт корректный скелет, в который автор досыпает детали. Используй, когда «написать туториал», «оформить пошаговую инструкцию», «how-to», «tutorial»,«гайд по развёртыванию», «инструкция, как сделать X».From its SKILL.md

Install

npx -y skills add jtprogru/bear-skills --skill content-tutorial-structure

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

7.6 KB, as published. Nobody here has run it

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> без объяснения
не пропускай раздел проверки — это то, что отличает туториал от блог-поста