ddadmin
d4e6d84524
- Зачем:
- следующая сессия продолжает работу над документацией с фокусом на
корневой README; нужен контекст (модель курса, голос, подходы), а не
чек-лист задач.
- Что:
- добавлен .scratch/handoffs/2026-06-06-root-readme-polish.md: модель
курса, линза mentee-first, рабочие подходы, состояние git и рабочего
дерева, направление по корневому README (без предписаний).
- Проверка:
- чистый .md, прогон стенда не нужен.
69 lines
6.1 KiB
Markdown
69 lines
6.1 KiB
Markdown
# Handoff: контекст для работы над документацией курса
|
|
|
|
Дата: 2026-06-06 · Язык сессии: русский
|
|
|
|
Следующая сессия продолжает работу над документацией. Ближайший фокус — **корневой
|
|
[`README.md`](../../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` — для коммита.
|