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

Словарь справочников world.md и stand.md: термины и кальки #214

New Issue
Closed
opened 2026-09-01 23:05:46 +03:00 by ddmitry · 1 comment
ddmitry commented 2026-09-01 23:05:46 +03:00
Owner
Copy link
Copy source

Part of #206

Вопрос

Справочники docs/architecture/world.md и docs/architecture/stand.md собраны из текста README, который писался в ходе разработки. Владелец при беглом чтении PR #213 нашел, что часть слов там смешна или читается калькой с английского. Читатель справочников — человек со стороны, и ему такие слова режут глаз. Какие термины проекта менять, на что, и как вычитать оба файла целиком.

Что уже сделано в PR #213

Локальные кальки сняты по месту: заголовок «Как позвать генератор» стал «Как запустить генератор», переписаны абзацы «Умолчания есть не у всего, и это нарочно» и «Плата названа вслух… Открывает дверь не монтирование». Ледгер «Что проверено» в stand.md разбит на абзацы по темам.

Что осталось: термины словаря проекта

Эти слова — термины CONTEXT.md и ADR, они живут в коде, документах и лабах. Менять их по месту в одном файле нельзя: разойдется словарь.

Термин Замечание владельца Где живет
Пульт мира смешное название; в разработке на это закрывали глаза, в документах читатель будет смеяться CONTEXT.md, ADR 0009, 5 файлов
Опись мира звучит как инвентаризация в бухгалтерии CONTEXT.md, ADR, data/world-inventory.json, 10 файлов
Работник (worker) «работник берет из world_position» — забавно ADR 0009, 11 файлов, 51 вхождение
Сырье (raw, STG) так не говорят storage.md и еще 27 файлов, 133 вхождения

Веер замен собрать при старте тикета по скиллу brainstorm-with-docs; решение — в CONTEXT.md и ADR тем же PR, тексты справочников и лаб правит Codex по списку.

Что осталось: глубокая вычитка

Владелец читал бегло; оба файла нужно прочесть целиком свежими глазами с оптикой литературного русского: кальки, канцелярит, шутливые обороты времен разработки. Читает модель с высокой грамотностью в свежей сессии, находки — списком владельцу, правки по месту после его отбора.

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

  • По каждому из четырех терминов принято решение: оставить или заменить, на что.
  • Принятые замены внесены в CONTEXT.md, ADR (пометкой, не переписыванием истории) и во все документы, где термин встречается; имена в коде (world_*, world-inventory.json) — отдельное решение, названное явно.
  • world.md и stand.md прочитаны целиком свежей сессией, находки отобраны владельцем и внесены.
  • Скрипт ссылок из тикета #212 дает пустой вывод; make config-test зеленый.

Границы

  • README не пересобирать: это следующий тикет карты.
  • Смысл текста не менять, только слова и строй фраз.

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

  • Резолюция #212 (комментарий) и обсуждение PR #213.
  • CONTEXT.md — статьи «Опись мира», «Пульт мира».
  • ADR 0009 — «Работники» и «Выключатель».
  • AGENTS.md, раздел «Язык».
Part of #206 ## Вопрос Справочники `docs/architecture/world.md` и `docs/architecture/stand.md` собраны из текста README, который писался в ходе разработки. Владелец при беглом чтении PR #213 нашел, что часть слов там смешна или читается калькой с английского. Читатель справочников — человек со стороны, и ему такие слова режут глаз. Какие термины проекта менять, на что, и как вычитать оба файла целиком. ## Что уже сделано в PR #213 Локальные кальки сняты по месту: заголовок «Как позвать генератор» стал «Как запустить генератор», переписаны абзацы «Умолчания есть не у всего, и это нарочно» и «Плата названа вслух… Открывает дверь не монтирование». Ледгер «Что проверено» в stand.md разбит на абзацы по темам. ## Что осталось: термины словаря проекта Эти слова — термины CONTEXT.md и ADR, они живут в коде, документах и лабах. Менять их по месту в одном файле нельзя: разойдется словарь. | Термин | Замечание владельца | Где живет | |---|---|---| | **Пульт мира** | смешное название; в разработке на это закрывали глаза, в документах читатель будет смеяться | CONTEXT.md, ADR 0009, 5 файлов | | **Опись мира** | звучит как инвентаризация в бухгалтерии | CONTEXT.md, ADR, `data/world-inventory.json`, 10 файлов | | **Работник** (worker) | «работник берет из world_position» — забавно | ADR 0009, 11 файлов, 51 вхождение | | **Сырье** (raw, STG) | так не говорят | storage.md и еще 27 файлов, 133 вхождения | Веер замен собрать при старте тикета по скиллу `brainstorm-with-docs`; решение — в CONTEXT.md и ADR тем же PR, тексты справочников и лаб правит Codex по списку. ## Что осталось: глубокая вычитка Владелец читал бегло; оба файла нужно прочесть целиком свежими глазами с оптикой литературного русского: кальки, канцелярит, шутливые обороты времен разработки. Читает модель с высокой грамотностью в свежей сессии, находки — списком владельцу, правки по месту после его отбора. ## Критерии приемки - [x] По каждому из четырех терминов принято решение: оставить или заменить, на что. - [x] Принятые замены внесены в CONTEXT.md, ADR (пометкой, не переписыванием истории) и во все документы, где термин встречается; имена в коде (`world_*`, `world-inventory.json`) — отдельное решение, названное явно. - [x] `world.md` и `stand.md` прочитаны целиком свежей сессией, находки отобраны владельцем и внесены. - [x] Скрипт ссылок из тикета #212 дает пустой вывод; `make config-test` зеленый. ## Границы - README не пересобирать: это следующий тикет карты. - Смысл текста не менять, только слова и строй фраз. ## Сначала прочитать - Резолюция #212 (комментарий) и обсуждение PR #213. - CONTEXT.md — статьи «Опись мира», «Пульт мира». - ADR 0009 — «Работники» и «Выключатель». - AGENTS.md, раздел «Язык».
ddmitry added the wayfinder:grilling label 2026-09-01 23:05:46 +03:00
ddmitry self-assigned this 2026-09-01 23:31:37 +03:00
ddmitry commented 2026-09-02 16:48:17 +03:00
Author
Owner
Copy link
Copy source

Сделано в PR #215 (ждёт слияния владельцем).

Термины. Веер собран по brainstorm-with-docs, выбор владельца 2026-09-02:

  • «пульт мира» → даги модельного времени, коротко «даги времени». world.md теперь «Мир и модельное время», раздел и якорь #даги-модельного-времени, тег дагов в Airflow — «модельное время». Отвергнуты: оставить как есть (читатель смеётся), «управление миром» (CONTEXT.md уже запретил «управляющие даги», звучит как игра в бога), «ход мира» (ещё одна метафора), без общего имени (в ADR 0009 слово нужно десяток раз).
  • «опись мира» → паспорт мира; бывшая шапка «паспорт» стала «шапкой паспорта». Отвергнуты: оставить (бухгалтерский оттенок), «эталон мира» (занято стартовым миром), «контрольные суммы мира» (три слова, не склоняется в речи).
  • «работник» → шаговый даг: исполняет «пошаговый режим» из словаря, ассоциация с шаговым двигателем уместна. Отвергнуты: «игрок» (та же болезнь с другой стороны), «исполнитель» (занято агентами), без общего имени.
  • «сырьё» → сырые данные (содержимое), сырой слой (слой), STG (конкретная таблица или база). Отвергнуты: оставить, STG повсюду (аббревиатура через слово), «приёмный слой» (столкновение с «приёмом» как процессом).

Имена в коде не тронуты и названы явно: world_control.py, world-inventory.json, inventory.py, make inventory, stg.*_raw; соответствие держит CONTEXT.md. Единственное исключение — тег дага, он виден в интерфейсе.

Где записано. CONTEXT.md: статьи «Паспорт мира», «Даги модельного времени», новые «Шаговый даг» и «Сырые данные», старые слова в строках «Избегать». Пометка «Позднее тикет #214 сменил имена…» в ADR 0005, 0008 и 0009 — там, где термин стоит в заголовке или встречается пять и более раз; текст ADR не переписан. В остальных ADR и в docs/research старые слова оставлены намеренно: это история, соответствие даёт словарь. Замены в живом тексте: README, справочники, путеводитель, лабы, спеки, комментарии дагов и SQL, панель Grafana — 50 файлов, разнёс Codex по списку.

Вычитка. Sol свежим тредом прочёл оба файла целиком: 49 находок. Внесены 35, четыре частично («всякой лабы» → «каждой лабы», «ходит за подложкой» → «читает подложку», «секция» → «раздел», «краснеет» → «падает»). Отклонены как термины репозитория: «лаба», «подложка», «ноды», «дашборд», «закреплён», «в бою». Отклонены по смыслу: устаревшая фраза про «даг этапа 5» (хвост тикета пересборки README), инструкция «Снимите — мир поедет сам» (короче и яснее замены). Не тронуты по умолчанию, владелец может вернуть: «Спрашивают его двое», абзац про умолчания генератора. Регистр по оценке Sol: оба файла читаются как документация, следы разработки сидели в разделах про запуск генератора, даги времени, роли ClickHouse и «Что проверено».

Ревью. Саморевью Codex: 10 найдено, 10 закрыто. Слепое ревью Sonnet: два major и один nit, закрыты — сломанное местоимение после замены в storage.md, строка журнала решений в спеке генератора, которую замена сделала ложной (восстановлено «опись мира» с пометкой про #214), разнобой «Keeper». Codex после этого перевёрстал свои абзацы под 80 знаков, перепроверка Sonnet: APPROVED.

Проверка. Скрипт ссылок из #212 пуст; якоря #пульт-мира нет; старые слова только в ADR, research и CONTEXT.md; make config-test зелёный; make lint в корне и в generator/; make test в generator/ — 437 passed.

Хвосты. Фраза «так генератор позовёт даг этапа 5» в world.md по-прежнему устарела — в тикет пересборки README. Заголовок ADR 0009 остался «Пульт мира…» намеренно.

Сделано в PR #215 (ждёт слияния владельцем). **Термины.** Веер собран по `brainstorm-with-docs`, выбор владельца 2026-09-02: - «пульт мира» → **даги модельного времени**, коротко «даги времени». world.md теперь «Мир и модельное время», раздел и якорь `#даги-модельного-времени`, тег дагов в Airflow — «модельное время». Отвергнуты: оставить как есть (читатель смеётся), «управление миром» (CONTEXT.md уже запретил «управляющие даги», звучит как игра в бога), «ход мира» (ещё одна метафора), без общего имени (в ADR 0009 слово нужно десяток раз). - «опись мира» → **паспорт мира**; бывшая шапка «паспорт» стала «шапкой паспорта». Отвергнуты: оставить (бухгалтерский оттенок), «эталон мира» (занято стартовым миром), «контрольные суммы мира» (три слова, не склоняется в речи). - «работник» → **шаговый даг**: исполняет «пошаговый режим» из словаря, ассоциация с шаговым двигателем уместна. Отвергнуты: «игрок» (та же болезнь с другой стороны), «исполнитель» (занято агентами), без общего имени. - «сырьё» → **сырые данные** (содержимое), **сырой слой** (слой), **STG** (конкретная таблица или база). Отвергнуты: оставить, STG повсюду (аббревиатура через слово), «приёмный слой» (столкновение с «приёмом» как процессом). Имена в коде не тронуты и названы явно: `world_control.py`, `world-inventory.json`, `inventory.py`, `make inventory`, `stg.*_raw`; соответствие держит CONTEXT.md. Единственное исключение — тег дага, он виден в интерфейсе. **Где записано.** CONTEXT.md: статьи «Паспорт мира», «Даги модельного времени», новые «Шаговый даг» и «Сырые данные», старые слова в строках «Избегать». Пометка «Позднее тикет #214 сменил имена…» в ADR 0005, 0008 и 0009 — там, где термин стоит в заголовке или встречается пять и более раз; текст ADR не переписан. В остальных ADR и в docs/research старые слова оставлены намеренно: это история, соответствие даёт словарь. Замены в живом тексте: README, справочники, путеводитель, лабы, спеки, комментарии дагов и SQL, панель Grafana — 50 файлов, разнёс Codex по списку. **Вычитка.** Sol свежим тредом прочёл оба файла целиком: 49 находок. Внесены 35, четыре частично («всякой лабы» → «каждой лабы», «ходит за подложкой» → «читает подложку», «секция» → «раздел», «краснеет» → «падает»). Отклонены как термины репозитория: «лаба», «подложка», «ноды», «дашборд», «закреплён», «в бою». Отклонены по смыслу: устаревшая фраза про «даг этапа 5» (хвост тикета пересборки README), инструкция «Снимите — мир поедет сам» (короче и яснее замены). Не тронуты по умолчанию, владелец может вернуть: «Спрашивают его двое», абзац про умолчания генератора. Регистр по оценке Sol: оба файла читаются как документация, следы разработки сидели в разделах про запуск генератора, даги времени, роли ClickHouse и «Что проверено». **Ревью.** Саморевью Codex: 10 найдено, 10 закрыто. Слепое ревью Sonnet: два major и один nit, закрыты — сломанное местоимение после замены в storage.md, строка журнала решений в спеке генератора, которую замена сделала ложной (восстановлено «опись мира» с пометкой про #214), разнобой «Keeper». Codex после этого перевёрстал свои абзацы под 80 знаков, перепроверка Sonnet: APPROVED. **Проверка.** Скрипт ссылок из #212 пуст; якоря `#пульт-мира` нет; старые слова только в ADR, research и CONTEXT.md; `make config-test` зелёный; `make lint` в корне и в `generator/`; `make test` в `generator/` — 437 passed. **Хвосты.** Фраза «так генератор позовёт даг этапа 5» в world.md по-прежнему устарела — в тикет пересборки README. Заголовок ADR 0009 остался «Пульт мира…» намеренно.
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.
Depends on
#212 Переезд операторских разделов README в справочники
ddmitry/clickstream-data-platform
Reference: ddmitry/clickstream-data-platform#214