ddmitry/clickstream-data-platform
1
0 Fork 0
Code Issues 5 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Скелет путеводителя и README-шапка #209

New Issue
Closed
opened 2026-09-01 20:52:20 +03:00 by ddmitry · 2 comments
ddmitry commented 2026-09-01 20:52:20 +03:00
Owner
Copy link
Copy source

Part of #206

Первый рабочий тикет очереди из резолюции #208: скелет путеводителя и
шапка README. По правилу карты тикет — работа, не решение.

Цель

Менти, впервые открывший репозиторий, с первого экрана понимает, что перед
ним и куда идти дальше: корневой README встречает человеческой шапкой, а
docs/handbook/README.md ведёт тропой «глоссарий → архитектура → уроки» и
называет будущие главы.

Что сделать

1. docs/handbook/README.md — вход и порядок чтения.

  • Зачин: что такое путеводитель и для кого — менти, который видит стенд
    впервые и хочет в нём разобраться до уроков.
  • Тропа чтения: словарь понятий CONTEXT.md → главы
    путеводителя → справочники docs/architecture/ → уроки
    docs/labs/. Словарь подать честно: это справочник,
    к которому возвращаются за незнакомым словом, а не чтение подряд — его
    первые статьи описывают внутренности генератора, менти они понадобятся
    нескоро.
  • Список будущих глав, каждая — аннотация в одну-две строки (о чём глава и
    чему учит) плюс временная ссылка «пока главы нет — смотреть …»:
  • Файлов-заглушек глав не создавать: глава появляется файлом вместе с
    текстом (следующий тикет очереди). Ссылок на несуществующие файлы в
    README путеводителя нет.

2. Шапка корневого README.md — точечный пересмотр.

  • Сразу после заголовка — один-два человеческих абзаца вместо нынешних двух
    строк: для кого стенд и что с ним делать — не повторяя заголовок, а
    отвечая на вопросы, которых в нём нет. Четыре действия: поднять
    («Быстрый старт» ниже), выключить (make down), разобраться
    (путеводитель), учиться
    (уроки). Строка о предшественнике остаётся в шапке.
  • В разделе «Документация» первой строкой добавить docs/handbook/ с одной
    фразой о жанре, следом — строку про docs/labs/: уроки в этом списке
    сейчас не названы вовсе, хотя шапка на них ссылается.
  • Остальные разделы README не трогать: операторские разделы остаются как
    есть, просто перестают быть первым, что видит новичок.

3. Пункт о docs/handbook/ в AGENTS.md, раздел «Структура».

  • Правило имён как у docs/labs/: слаг строчными латинскими буквами через
    дефис, индекс папки — README.md, глава — живой документ без даты и
    номера. Один пункт списка; пишет Fable на приёмке, не Sol.

Слово «путеводитель» дальше в репозитории означает docs/handbook/.
Страницу docs/architecture/generator/README.md в аннотациях путеводителем
не называть: там это слово живёт в узком смысле — путеводитель по
устройству генератора.

Критерии приёмки

  • docs/handbook/README.md существует: зачин, тропа чтения, пять
    аннотированных глав с временными ссылками.
  • Шапка README: человеческий зачин с четырьмя действиями (поднять,
    выключить, разобраться, учиться); строка про docs/handbook/ в
    разделе «Документация»; прочие разделы без правок.
  • Все относительные ссылки обоих файлов ведут на существующие файлы
    или разделы.
  • В AGENTS.md, раздел «Структура», есть пункт про docs/handbook/ с
    правилом имён.
  • Проза прошла фильтры приёмки: ai-text-lint и оптика литературного
    русского.

Границы

  • Главы путеводителя не писать — только аннотации в его README.
  • Интерактивную карту архитектуры не начинать.
  • Справочники docs/architecture/, доки лаб и операторские разделы README
    не править.
  • Тире и ёлочки в существующем тексте не трогать; в новом тексте «ё» не
    писать (правило репозитория с 2026-08-26).

Сначала прочитать

  • Резолюция тикета #208 (комментарий) — принятая форма и структура.
  • README.md целиком — что уже сказано и где.
  • CONTEXT.md (первые экраны) — жанр словаря.
  • docs/labs/README.md — тон и жанр учебного текста репозитория.
  • Оглавления docs/architecture/ — куда ведут временные ссылки.

Кто пишет

Постановка и вкусовые решения — Fable (эта сессия). Русская проза обоих
файлов — Sol (gpt-5.6-sol) по этой постановке. Проверка ссылок и фактов —
оркестратор.

Проверка

  • Ссылки — командой из корня репозитория (пусто — значит, все цели на
    месте):

    for f in docs/handbook/README.md README.md; do
  d=$(dirname "$f")
  grep -oE '\]\([^)]+\)' "$f" | sed -E 's/^\]\(//; s/\)$//; s/#.*$//' \
    | grep -vE '^(https?:|$)' | sort -u \
    | while read -r p; do [ -e "$d/$p" ] || echo "$f -> $p MISSING"; done
done

  • make lint не задевается (правки только в markdown), смоук не нужен.

Part of #206 Первый рабочий тикет очереди из резолюции #208: скелет путеводителя и шапка README. По правилу карты тикет — работа, не решение. ## Цель Менти, впервые открывший репозиторий, с первого экрана понимает, что перед ним и куда идти дальше: корневой README встречает человеческой шапкой, а `docs/handbook/README.md` ведёт тропой «глоссарий → архитектура → уроки» и называет будущие главы. ## Что сделать **1. `docs/handbook/README.md` — вход и порядок чтения.** - Зачин: что такое путеводитель и для кого — менти, который видит стенд впервые и хочет в нём разобраться до уроков. - Тропа чтения: словарь понятий [`CONTEXT.md`](../../CONTEXT.md) → главы путеводителя → справочники `docs/architecture/` → уроки [`docs/labs/`](../labs/README.md). Словарь подать честно: это справочник, к которому возвращаются за незнакомым словом, а не чтение подряд — его первые статьи описывают внутренности генератора, менти они понадобятся нескоро. - Список будущих глав, каждая — аннотация в одну-две строки (о чём глава и чему учит) плюс временная ссылка «пока главы нет — смотреть …»: - хранилище и его слои — пока: [`docs/architecture/storage.md`](../architecture/storage.md); - потоки Airflow и пульт мира — пока: [`docs/architecture/etl.md`](../architecture/etl.md) и раздел «Пульт мира» корневого README; - мониторинг: куда смотреть — пока: [`docs/architecture/monitoring/`](../architecture/monitoring/README.md); - немного Superset — пока: [`docs/architecture/superset.md`](../architecture/superset.md); - генератор: откуда берутся данные — пока: [`generator/`](../../generator/) и [`docs/formats/clickstream-event.md`](../formats/clickstream-event.md). - Файлов-заглушек глав не создавать: глава появляется файлом вместе с текстом (следующий тикет очереди). Ссылок на несуществующие файлы в README путеводителя нет. **2. Шапка корневого `README.md` — точечный пересмотр.** - Сразу после заголовка — один-два человеческих абзаца вместо нынешних двух строк: для кого стенд и что с ним делать — не повторяя заголовок, а отвечая на вопросы, которых в нём нет. Четыре действия: поднять («Быстрый старт» ниже), выключить (`make down`), разобраться ([путеводитель](docs/handbook/README.md)), учиться ([уроки](docs/labs/README.md)). Строка о предшественнике остаётся в шапке. - В разделе «Документация» первой строкой добавить `docs/handbook/` с одной фразой о жанре, следом — строку про `docs/labs/`: уроки в этом списке сейчас не названы вовсе, хотя шапка на них ссылается. - Остальные разделы README не трогать: операторские разделы остаются как есть, просто перестают быть первым, что видит новичок. **3. Пункт о `docs/handbook/` в AGENTS.md, раздел «Структура».** - Правило имён как у `docs/labs/`: слаг строчными латинскими буквами через дефис, индекс папки — `README.md`, глава — живой документ без даты и номера. Один пункт списка; пишет Fable на приёмке, не Sol. **Слово «путеводитель»** дальше в репозитории означает `docs/handbook/`. Страницу `docs/architecture/generator/README.md` в аннотациях путеводителем не называть: там это слово живёт в узком смысле — путеводитель по устройству генератора. ## Критерии приёмки - [x] `docs/handbook/README.md` существует: зачин, тропа чтения, пять аннотированных глав с временными ссылками. - [x] Шапка README: человеческий зачин с четырьмя действиями (поднять, выключить, разобраться, учиться); строка про `docs/handbook/` в разделе «Документация»; прочие разделы без правок. - [x] Все относительные ссылки обоих файлов ведут на существующие файлы или разделы. - [x] В AGENTS.md, раздел «Структура», есть пункт про `docs/handbook/` с правилом имён. - [x] Проза прошла фильтры приёмки: `ai-text-lint` и оптика литературного русского. ## Границы - Главы путеводителя не писать — только аннотации в его README. - Интерактивную карту архитектуры не начинать. - Справочники `docs/architecture/`, доки лаб и операторские разделы README не править. - Тире и ёлочки в существующем тексте не трогать; в новом тексте «ё» не писать (правило репозитория с 2026-08-26). ## Сначала прочитать - Резолюция тикета #208 (комментарий) — принятая форма и структура. - `README.md` целиком — что уже сказано и где. - `CONTEXT.md` (первые экраны) — жанр словаря. - `docs/labs/README.md` — тон и жанр учебного текста репозитория. - Оглавления `docs/architecture/` — куда ведут временные ссылки. ## Кто пишет Постановка и вкусовые решения — Fable (эта сессия). Русская проза обоих файлов — Sol (gpt-5.6-sol) по этой постановке. Проверка ссылок и фактов — оркестратор. ## Проверка - Ссылки — командой из корня репозитория (пусто — значит, все цели на месте): ```bash for f in docs/handbook/README.md README.md; do d=$(dirname "$f") grep -oE '\]\([^)]+\)' "$f" | sed -E 's/^\]\(//; s/\)$//; s/#.*$//' \ | grep -vE '^(https?:|$)' | sort -u \ | while read -r p; do [ -e "$d/$p" ] || echo "$f -> $p MISSING"; done done ``` - `make lint` не задевается (правки только в markdown), смоук не нужен.
ddmitry added the wayfinder:task label 2026-09-01 20:52:35 +03:00
ddmitry self-assigned this 2026-09-01 20:52:36 +03:00
ddmitry commented 2026-09-01 20:59:52 +03:00
Author
Owner
Copy link
Copy source

Ревью постановки (Опус, свежая сессия): 1 major, 3 minor, 3 nit. Внесено в тело: подача словаря CONTEXT.md как справочника, а не чтения подряд; строка про docs/labs/ в разделе «Документация» README; команда проверки ссылок; пункт о docs/handbook/ в AGENTS.md; развод слова «путеводитель» с докой генератора; зачин шапки не повторяет заголовок. Отклонено: SPEC-6 (проверку ссылок вести Codex'ом) — на два файла отдельный тред дороже пользы, проверяет оркестратор командой из тикета.

Ревью постановки (Опус, свежая сессия): 1 major, 3 minor, 3 nit. Внесено в тело: подача словаря CONTEXT.md как справочника, а не чтения подряд; строка про docs/labs/ в разделе «Документация» README; команда проверки ссылок; пункт о docs/handbook/ в AGENTS.md; развод слова «путеводитель» с докой генератора; зачин шапки не повторяет заголовок. Отклонено: SPEC-6 (проверку ссылок вести Codex'ом) — на два файла отдельный тред дороже пользы, проверяет оркестратор командой из тикета.
ddmitry commented 2026-09-01 21:16:27 +03:00
Author
Owner
Copy link
Copy source

Резолюция: сделано, ждет слияния PR #210 (Closes #209 закроет тикет сам).

  • docs/handbook/README.md — вход путеводителя: тропа чтения и пять аннотированных будущих глав с временными ссылками; заглушек нет.
  • Шапка README.md — для менти: четыре действия, ссылки на путеводитель и уроки; «Документация» получила строки handbook и labs; операторские разделы byte-identical.
  • AGENTS.md — правило имен docs/handbook/.

Конвейер: проза — Sol; ревью постановки — Опус (1 major: подача словаря; внесен); слепое ревью — Опус, свежая сессия (1 minor, 2 nit — исправлены, перепроверка ALL_FIXED); приёмка — ai-text-lint + литературный русский (одна правка). Проверка ссылок из тикета — пустой вывод.

Резолюция: сделано, ждет слияния PR #210 (Closes #209 закроет тикет сам). - docs/handbook/README.md — вход путеводителя: тропа чтения и пять аннотированных будущих глав с временными ссылками; заглушек нет. - Шапка README.md — для менти: четыре действия, ссылки на путеводитель и уроки; «Документация» получила строки handbook и labs; операторские разделы byte-identical. - AGENTS.md — правило имен docs/handbook/. Конвейер: проза — Sol; ревью постановки — Опус (1 major: подача словаря; внесен); слепое ревью — Опус, свежая сессия (1 minor, 2 nit — исправлены, перепроверка ALL_FIXED); приёмка — ai-text-lint + литературный русский (одна правка). Проверка ссылок из тикета — пустой вывод.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wayfinder:task
wontfix
No labels wayfinder:task
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ddmitry (Dmitry Dementiev)
No Assignees ddmitry
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ddmitry/clickstream-data-platform#209