ddadmin
d4e6d84524
- Зачем:
- следующая сессия продолжает работу над документацией с фокусом на
корневой README; нужен контекст (модель курса, голос, подходы), а не
чек-лист задач.
- Что:
- добавлен .scratch/handoffs/2026-06-06-root-readme-polish.md: модель
курса, линза mentee-first, рабочие подходы, состояние git и рабочего
дерева, направление по корневому README (без предписаний).
- Проверка:
- чистый .md, прогон стенда не нужен.
6.1 KiB
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 — по slugecommerce-analytics. Стоит сверить при правке.
Suggested skills
ai-text-lint— прогон правок доков на AI-маркеры (contextarticle, house style не снимать).conventional-commits— для коммита.