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

Пересмотр тела корневого README #211

New Issue
Closed
opened 2026-09-01 21:35:33 +03:00 by ddmitry · 1 comment
ddmitry commented 2026-09-01 21:35:33 +03:00
Owner
Copy link
Copy source

Part of #206

Вопрос

Корневой README — склад сведений, осевших там, где писались, а не цельный
документ: под «Быстрым стартом» живёт справочник смоука и healthcheck'ов,
«Статус» — сводка о постройке, «Состав и доступ» — операторская таблица.
Решить, что остаётся лицом репозитория, что и куда переезжает — в
справочники docs/architecture/, в главы путеводителя docs/handbook/, —
а что умирает. Знания при этом не теряются: каждый выселенный кусок
получает адрес.

Вторая часть развилки — адресация читателя. Слово «менти» в README и
путеводителе режет глаз владельцу; заменить нейтральной формулировкой в
духе «Этот стенд — для изучения и экспериментов с кликстримом и
ClickHouse…». Решение распространяется на оба файла: шапку README и
docs/handbook/README.md.

Развилка ведётся грилингом с владельцем (brainstorm-with-docs): веер
вариантов раскладки, потом конвергенция. Итог тикета — принятая раскладка
(что где живёт) плюс постановка работ по переезду; сам переезд — следующими
тикетами очереди.

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

  • README.md целиком — предмет пересмотра.
  • Резолюция #208 и итог #209: шапка уже переписана и станет первым абзацем
    будущего README (с поправкой на адресацию читателя).
  • docs/handbook/README.md — принимающая сторона переезда.
  • docs/architecture/testing.md — туда просится справочный материал
    «Быстрого старта».
Part of #206 ## Вопрос Корневой README — склад сведений, осевших там, где писались, а не цельный документ: под «Быстрым стартом» живёт справочник смоука и healthcheck'ов, «Статус» — сводка о постройке, «Состав и доступ» — операторская таблица. Решить, что остаётся лицом репозитория, что и куда переезжает — в справочники `docs/architecture/`, в главы путеводителя `docs/handbook/`, — а что умирает. Знания при этом не теряются: каждый выселенный кусок получает адрес. Вторая часть развилки — адресация читателя. Слово «менти» в README и путеводителе режет глаз владельцу; заменить нейтральной формулировкой в духе «Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse…». Решение распространяется на оба файла: шапку README и `docs/handbook/README.md`. Развилка ведётся грилингом с владельцем (`brainstorm-with-docs`): веер вариантов раскладки, потом конвергенция. Итог тикета — принятая раскладка (что где живёт) плюс постановка работ по переезду; сам переезд — следующими тикетами очереди. ## Сначала прочитать - `README.md` целиком — предмет пересмотра. - Резолюция #208 и итог #209: шапка уже переписана и станет первым абзацем будущего README (с поправкой на адресацию читателя). - `docs/handbook/README.md` — принимающая сторона переезда. - `docs/architecture/testing.md` — туда просится справочный материал «Быстрого старта».
ddmitry added the wayfinder:grilling label 2026-09-01 21:35:42 +03:00
ddmitry self-assigned this 2026-09-01 21:40:56 +03:00
ddmitry commented 2026-09-01 22:06:10 +03:00
Author
Owner
Copy link
Copy source

Резолюция принята владельцем в живом обсуждении.

Что такое README

Лицо репозитория: то, что нужно в первую очередь. Четыре блока сверху вниз:

  1. Промо-блок первой строкой под заголовком, цитатой, по образцу стенда
    airflow-greenplum: стендом можно пользоваться самостоятельно, он же
    курсовая работа плана обучения, за помощью к ментору. Ссылка на план —
    https://de.dementev.space (не на замороженный аккаунт GitHub), контакт
    ментора — как у соседа.
  2. Куда я попал: шапка из #209 плюс одна фраза о составе и пути данных.
    Без схемы: интерактивная карта запланирована в путеводителе, вторую
    схему пришлось бы держать с ней в согласии.
  3. Типовые действия, которые делают, не уходя дальше README: поднять и
    проверить; адреса и пароли интерфейсов; сдвинуть мир на день или
    включить живой ход (два-три предложения со ссылкой в справочник, таблица
    дагов из README уходит); вернуть мир к началу; выключить и полный сброс;
    подключиться к ClickHouse из DBeaver под analyst — коротко, но
    отдельным разделом: это будут искать все.
  4. Ссылки: раздел «Документация» остается.

Обращение к читателю — «вы». Слово «менти» из README и
docs/handbook/README.md уходит: в этих двух файлах оно режет глаз владельцу.
В ТЗ лаб и спеках оно остается ролью в третьем лице.

Куда переезжает остальное

  • Доводы смоука и описания целей make (строки 74–123) — в
    docs/architecture/testing.md.
  • «Стартовый мир», «Как позвать генератор», «Пульт мира» — в новый
    docs/architecture/world.md «Мир и его пульт».
  • «Состав и доступ» без адресов и паролей — в новый
    docs/architecture/stand.md «Стенд: службы, доступ, настройка»; ледгер
    сверки с документацией — в его раздел «Что проверено».
  • Умирают: «Статус» (одна фраза о составе уходит в шапку), «Что здесь
    будет» (все пять пунктов выполнены), «Чем отличается от предшественника»
    (шапка уже говорит «преемник»).

У зон «службы и доступ» и «мир и его пульт» справочников не было, README
служил их складом; путеводитель ссылался на якорь README#пульт-мира именно
поэтому.

Очередь работ

Два тикета по одному: переезд в справочники (#212), затем пересборка README
по четырем блокам с адресацией обоих файлов. Дальше очередь #208: главы
путеводителя, интерактивная карта.

Отклоненные варианты

  • README как операторская книжка, учебное в путеводитель — склад
    прибирается, но остается складом на 350 строк.
  • Все в путеводитель — главы становятся справочниками, жанр по
    резолюции #208 размывается.
  • Отдельный жанр docs/runbooks/ — новый жанр и новое правило имен ради
    границы «устройство или процедура», которая в репозитории и так размыта.
  • Схема потока в README — до появления интерактивной карты лишняя.
  • Таблица дагов пульта в README — явно лишняя, ее место в справочнике.
Резолюция принята владельцем в живом обсуждении. ## Что такое README Лицо репозитория: то, что нужно в первую очередь. Четыре блока сверху вниз: 1. **Промо-блок** первой строкой под заголовком, цитатой, по образцу стенда airflow-greenplum: стендом можно пользоваться самостоятельно, он же курсовая работа плана обучения, за помощью к ментору. Ссылка на план — https://de.dementev.space (не на замороженный аккаунт GitHub), контакт ментора — как у соседа. 2. **Куда я попал**: шапка из #209 плюс одна фраза о составе и пути данных. Без схемы: интерактивная карта запланирована в путеводителе, вторую схему пришлось бы держать с ней в согласии. 3. **Типовые действия**, которые делают, не уходя дальше README: поднять и проверить; адреса и пароли интерфейсов; сдвинуть мир на день или включить живой ход (два-три предложения со ссылкой в справочник, таблица дагов из README уходит); вернуть мир к началу; выключить и полный сброс; подключиться к ClickHouse из DBeaver под `analyst` — коротко, но отдельным разделом: это будут искать все. 4. **Ссылки**: раздел «Документация» остается. Обращение к читателю — «вы». Слово «менти» из README и docs/handbook/README.md уходит: в этих двух файлах оно режет глаз владельцу. В ТЗ лаб и спеках оно остается ролью в третьем лице. ## Куда переезжает остальное - Доводы смоука и описания целей `make` (строки 74–123) — в docs/architecture/testing.md. - «Стартовый мир», «Как позвать генератор», «Пульт мира» — в новый docs/architecture/world.md «Мир и его пульт». - «Состав и доступ» без адресов и паролей — в новый docs/architecture/stand.md «Стенд: службы, доступ, настройка»; ледгер сверки с документацией — в его раздел «Что проверено». - Умирают: «Статус» (одна фраза о составе уходит в шапку), «Что здесь будет» (все пять пунктов выполнены), «Чем отличается от предшественника» (шапка уже говорит «преемник»). У зон «службы и доступ» и «мир и его пульт» справочников не было, README служил их складом; путеводитель ссылался на якорь README#пульт-мира именно поэтому. ## Очередь работ Два тикета по одному: переезд в справочники (#212), затем пересборка README по четырем блокам с адресацией обоих файлов. Дальше очередь #208: главы путеводителя, интерактивная карта. ## Отклоненные варианты - **README как операторская книжка, учебное в путеводитель** — склад прибирается, но остается складом на 350 строк. - **Все в путеводитель** — главы становятся справочниками, жанр по резолюции #208 размывается. - **Отдельный жанр docs/runbooks/** — новый жанр и новое правило имен ради границы «устройство или процедура», которая в репозитории и так размыта. - **Схема потока в README** — до появления интерактивной карты лишняя. - **Таблица дагов пульта в README** — явно лишняя, ее место в справочнике.
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:grilling
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#211