clickstream-ch-kafka-superset-demo/.scratch/handoffs/2026-06-06-root-readme-polish.md

Handoff: контекст для работы над документацией курса

Дата: 2026-06-06 · Язык сессии: русский

Следующая сессия продолжает работу над документацией. Ближайший фокус — корневой README.md: ощущение, что он слишком инженерно-демовый и требует более серьёзной переработки, чем косметика. Что именно с ним делать — решаем в новой сессии. Здесь — не план задач, а контекст и понимание, чтобы войти быстро.

Модель курса (держать в голове при любой правке доков)

• Аудитория и режим. Продвинутый менти, прошёл базу; идёт сам, ментор — на еженедельном созвоне (не «сессии»). Отсюда железное требование PRD: материал самодостаточен. Любой документ курса проверяю вопросом «менти поймёт это один, без ментора рядом?».
• Голос. Мягкий, уровень «обзорно», термин расшифровываем на первом употреблении, обращаемся на «ты». Правила — docs/course/LESSON_STANDARD.md §2/§5.
• House style — осознанный, линтером НЕ правим: тире «—», буква «ё», жирные зачины абзацев, двоеточие перед списком. ai-text-lint гоняем только на настоящие маркеры (канцелярит, зачины, хеджинг, negative parallelism).
• Принципы стенда: один паттерн на урок; данные — малый срез (LIMIT=50) ради быстрого повторяемого прогона (AGENTS.md). Это не мелочь — на этом я поймал баг (см. ниже).
• Крючок менторства. Тон роадмапа: «пройти можно самому — а можно с ментором, так быстрее/понятнее/лучше», CTA в Telegram @dementev_dev. Эталон тона — ~/sources/de-roadmap/README.md. Уже зеркально внесён в docs/course/README.md.

Линза, которую я применял (и которой не хватает корневому README)

Mentee-first vs author-first. docs/course/README.md был написан от автора — вёл читателя в PRD → LEARNING_PLAN → LESSON_STANDARD (мета-доки «зачем курс»), а не в уроки. Я переписал его от менти: сначала «что нужно до старта» и индекс уроков со ссылками, авторские доки убраны в секцию «Под капотом». Корневой README сейчас — про демо-стенд и DE-задание, курс в нём не упомянут вообще; он явный кандидат на ту же линзу, но, возможно, глубже (разделить «демо-стенд» и «вход в учебный курс»).

Подходы, которые сработали — стоит продолжить

• Проверять claim на стенде/в коде, а не на глаз. Так нашёлся баг: я сперва написал в course/README полную загрузку make data, хотя все уроки и правило среза требуют LIMIT=50 make data. Сверка с реальными уроками вскрыла расхождение.
• Свежий проход после написания ловит фактические нестыковки, не только стиль — именно он дал ту правку.
• Grep-линт на AI-маркеры с поправкой на house style быстрее сплошного чтения.
• Читать глазами целевого читателя: где точка входа, как ходить между частями, как стартовать с нуля.

Состояние (факты, которые понадобятся)

• Рабочее дерево: docs/course/README.md изменён, не закоммичен — это mentee-first редизайн + крючок менторства + правки свежего взгляда. Пользователь хочет закоммитить его (и правку корневого README, если будет) — после того как разберёмся с корневым.
• Git: ветка docs/advanced-clickstream-course, на ней параллельно пишет Codex (его bae1e02 уже лёг поверх моего d98ae9c). Строго аддитивно: не трогать чужие коммиты, git add только своих файлов, git fetch перед push. 2 локальных коммита не запушены.
• Сделано в этой сессии: d98ae9c (финальный ai-text-lint по урокам 0–6, синхрон PRD.md §7, уборка отработанных handoff'ов); docs/course/README.md переписан от менти. Уроки 0–6 как тексты готовы и единообразны.
• Мелочь на заметку: корневой README (стр. 78, 238) даёт Superset-дашборд как /superset/dashboard/1/, а урок 6 — по slug ecommerce-analytics. Стоит сверить при правке.

Suggested skills

• ai-text-lint — прогон правок доков на AI-маркеры (context article, house style не снимать).
• conventional-commits — для коммита.