From d4e6d845244797e3b4cd863237fe23bbce526a3c Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sat, 6 Jun 2026 19:06:29 +0300 Subject: [PATCH] =?UTF-8?q?docs(handoff):=20=D0=BA=D0=BE=D0=BD=D1=82=D0=B5?= =?UTF-8?q?=D0=BA=D1=81=D1=82=20=D0=B4=D0=BB=D1=8F=20=D0=BF=D0=B5=D1=80?= =?UTF-8?q?=D0=B5=D1=80=D0=B0=D0=B1=D0=BE=D1=82=D0=BA=D0=B8=20=D0=BA=D0=BE?= =?UTF-8?q?=D1=80=D0=BD=D0=B5=D0=B2=D0=BE=D0=B3=D0=BE=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - следующая сессия продолжает работу над документацией с фокусом на корневой README; нужен контекст (модель курса, голос, подходы), а не чек-лист задач. - Что: - добавлен .scratch/handoffs/2026-06-06-root-readme-polish.md: модель курса, линза mentee-first, рабочие подходы, состояние git и рабочего дерева, направление по корневому README (без предписаний). - Проверка: - чистый .md, прогон стенда не нужен. --- .../handoffs/2026-06-06-root-readme-polish.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 .scratch/handoffs/2026-06-06-root-readme-polish.md diff --git a/.scratch/handoffs/2026-06-06-root-readme-polish.md b/.scratch/handoffs/2026-06-06-root-readme-polish.md new file mode 100644 index 0000000..292a69d --- /dev/null +++ b/.scratch/handoffs/2026-06-06-root-readme-polish.md @@ -0,0 +1,68 @@ +# 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` — для коммита.