docs(handbook): четыре главы переписаны живым русским

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

Что: в четырех главах олицетворения заменены прямыми формулировками,
«позиция мира» и «шаговый даг» раскрыты через world_position и имена
дагов, паспорт мира описан по составу и назначению, окно слепка
заказов объяснено словами, режимы генератора и правило импорта
Superset сказаны прямо. Тире и стрелки оставлены: это домашний стиль.

Проверка: проверки тикета #220 на битые ссылки и запретные слова
пусты, строки прозы не длиннее 80 знаков, git diff --check чист.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs/handbook/airflow-dags.md

@@ -1,7 +1,7 @@
 # Потоки Airflow и даги модельного времени
 
-В Airflow есть два рода дагов. Даги модельного времени двигают мир вперед, а
+В Airflow два рода дагов. Даги мира создают мир и проигрывают модельные дни,
-дневной конвейер раскладывает прожитый день по слоям.
+а дневной конвейер раскладывает сыгранный день по слоям хранилища.
 
 ```mermaid
 flowchart LR
@@ -18,21 +18,21 @@ flowchart LR
 материализованные представления переносят строки из STG в ODS без участия
 Airflow.
 
-Заказы приходят в топик `orders` слепком раз в модельные сутки. У слепка есть
+Заказы приходят в топик `orders` один раз в модельные сутки, целым слепком. У
-начало и конец, поэтому даг `orders_ingest` забирает его целиком. Такой способ
+слепка есть начало и конец, поэтому даг `orders_ingest` забирает его одной
-приема называется [пакетным забором](../../CONTEXT.md).
+порцией. Такой способ приема называется [пакетным](../../CONTEXT.md).
 
 ## Даги мира
 
-Два дага с тегом «жизненный цикл мира» создают мир:
+Два дага с тегом «жизненный цикл мира» отвечают за стартовый мир:
 
 | Даг | Что делает |
 |---|---|
 | `world_initialize` | Создает стартовый мир, если его еще нет |
-| `world_recreate` | Удаляет только прикладной мир и создает его заново |
+| `world_recreate` | Стирает данные мира и собирает стартовый мир заново |
 
-Три дага с тегом «модельное время» двигают ось. Дагами модельного времени
+Три дага с тегом «модельное время» проигрывают следующие дни. Именно их
-называют только их.
+называют дагами модельного времени.
 
 | Даг | Что делает |
 |---|---|
@@ -40,43 +40,47 @@ Airflow.
 | `world_live_day` | Играет следующий день в темпе модельного времени |
 | `world_live` | Запускает живые дни один за другим, пока снят с паузы |
 
-Позиция мира — переменная Airflow `world_position`, номер первого несыгранного
+Сколько дней уже сыграно, стенд помнит в переменной Airflow `world_position`:
-дня. Шаговый даг ставит ее только после успешного дня: оборванный прогон позицию
+в ней лежит номер первого несыгранного дня. `world_next_day` и `world_live_day`
-не двигает.
+записывают новое значение только после успешно сыгранного дня; оборванный
+прогон его не меняет.
 
-Сыграв день D, шаговый даг отправляет слепок заказов дня D−1 и ждет
+Сыграв день D, эти два дага отправляют слепок заказов за день D−1 и ждут, пока
-`orders_ingest`. Эти связи разобраны в [справочнике
+`orders_ingest` его примет. Эти связи разобраны в [справочнике
 мира](../architecture/world.md#даги-модельного-времени).
 
 ## Дневной конвейер
 
 У `etl_pipeline` нет своей обработки. Он по очереди запускает `dds_transform`,
-`dm_transform` и `dq_check` и ждет каждый даг. Параметров нет: объем работы
+`dm_transform` и `dq_check` и ждет каждый даг. Параметров у него нет: сколько
-конвейер выводит из позиции мира и состояния слоев. Поэтому один и тот же запуск
+дней обработать, он сам определяет по `world_position` и по тому, что уже лежит
-верен и когда его запустил другой даг, и когда вы нажали кнопку, и когда его
+в слоях. Поэтому один и тот же запуск верен и когда его запустил другой даг, и
-повторяют после сбоя. Детали есть в [справочнике
+когда вы нажали кнопку, и когда его повторяют после сбоя. Детали есть в
-конвейера](../architecture/etl.md#объём-прогона).
+[справочнике конвейера](../architecture/etl.md#объём-прогона).
 
-`world_next_day` не запускает конвейер. После пакетного шага слои догоняют мир
+`world_next_day` не запускает конвейер. После него слои хранилища отстают от
-только по вашей команде. `world_live_day`, наоборот, запускает `etl_pipeline` и
+мира, пока вы не запустите конвейер сами. `world_live_day`, наоборот,
-ждет его. Поэтому даг остается в работе и после конца модельного дня.
+запускает `etl_pipeline` и ждет его. Поэтому даг остается в работе и после
+конца модельного дня.
 
 ## Что значит красный
 
-Красный `etl_pipeline` не отменяет сыгранного дня: позиция уже записана. Чинится
+Красный `etl_pipeline` не отменяет сыгранного дня: `world_position` уже
-он перезапуском рукой — помнить о прошлом прогоне ничего не нужно. Кто запускает
+записана. Достаточно перезапустить конвейер рукой; разбираться, на чем
-конвейер, описано в [разделе о трех путях
+остановился прошлый прогон, не нужно. Кто запускает конвейер, описано в
-запуска](../architecture/etl.md#три-пути-запуска).
+[разделе о трех путях запуска](../architecture/etl.md#три-пути-запуска).
 
-Контур DQ проверяет данные. В дневном конвейере это `dq_check`: красная задача
+Качество данных проверяет контур DQ. В дневном конвейере это даг `dq_check`:
-печатает нарушенные ключи. Состав проверок описан в [разделе «Звено DQ
+упавшая задача печатает в лог ключи строк, не прошедших проверку. Состав
+проверок описан в [разделе «Звено DQ
 конвейера»](../architecture/dm.md#звено-dq-конвейера).
 
 ## Как найти в интерфейсе
 
 Даги мира ищите по тегам «модельное время» и «жизненный цикл мира». Остальные
 даги ищите по тегам «заказы», `etl`, `dds`, `dm` и `dq`. `homework_check` с
-тегами `dm` и `labs` проверяет домашние работы; о нем расскажут уроки.
+тегами `dm` и `labs` проверяет домашние работы; о нем рассказано в учебных
+заданиях.
 
 ## Посмотрите сами
 
@@ -102,9 +106,9 @@ ORDER BY report_date DESC
 LIMIT 3;
 ```
 
-Трафик получил сыгранный день, а выручка — только предыдущий: с этим ходом
+В трафике уже есть сыгранный день, а в выручке только предыдущий: вместе с этим
-приехал слепок предыдущего дня. Сыгранный день получит выручку на следующем
+днем пришел слепок заказов за предыдущий. Выручка сыгранного дня появится после
-ходу.
+следующего.
 
 ## Куда дальше
 

docs/handbook/generator.md

@@ -1,8 +1,8 @@
 # Генератор: откуда берутся данные
 
-Генератор притворяется двумя системами магазина. Счетчик сайта шлет события в
+Генератор изображает две системы интернет-магазина. Первая — счетчик на сайте,
-топик `hits`. Бэкенд раз в модельные сутки выгружает слепок заказов в топик
+он шлет события в топик `hits`. Вторая — бэкенд магазина, он раз в модельные
-`orders`.
+сутки выгружает слепок заказов в топик `orders`.
 
 ## Что он производит
 
@@ -10,19 +10,23 @@
 три вида событий: просмотр страницы, корзину и покупку. Все колонки перечислены
 в [описании выгрузки](../formats/clickstream-event.md).
 
-Заказ — вторая проекция той же покупки, с деньгами магазина. Заказ ездит в
+Заказ — та же покупка, но записанная бэкендом магазина, с суммами в деньгах.
-слепках, пока может измениться, — семь модельных дней. Устройство и форму слепка
+Семь модельных дней после оформления заказ еще может измениться, поэтому каждый
-разбирает [отдельный справочник](../architecture/orders/snapshot.md).
+дневной слепок несет заказы за последние семь дней в их текущем состоянии.
+Устройство и форма слепка разобраны в [отдельном
+справочнике](../architecture/orders/snapshot.md).
 
 ## Почему данные всегда одни и те же
 
-Модельный день зависит от [зерна](../architecture/generator/seeds.md) — числа,
+Генератор не берет случайность извне. Все его случайные решения выводятся из
-из которого генератор разворачивает всю свою случайность, — и от номера дня.
+[зерна](../architecture/generator/seeds.md) — одного числа в настройках — и из
-Одна и та же пара дает те же события, поэтому стартовый мир одинаков при каждом
+номера дня. То же зерно и тот же номер дня дают ровно те же события, поэтому
-`make up`.
+стартовый мир одинаков при каждом `make up`.
 
-Паспорт `data/world-inventory.json` отвечает на один вопрос: тот ли это мир. Он
+Рядом лежит паспорт мира, `data/world-inventory.json`: зерно, версия генератора
-охватывает только восемь дней стартового мира.
+и по строке на каждый день с числом событий и контрольной суммой. По нему
+проверяют, что генератор собрал тот же мир, что и раньше, и что в ODS все
+доехало без потерь. Паспорт описывает только восемь дней стартового мира.
 
 ## Кто его запускает
 
@@ -30,8 +34,9 @@
 времени](airflow-dags.md#даги-мира). Его можно запустить и напрямую. Команды
 собраны в [справочнике мира](../architecture/world.md#как-запустить-генератор).
 
-У генератора два режима. Пакетный отправляет день пачкой. Живой проигрывает
+У генератора два режима. Пакетный отправляет весь день разом. Живой шлет
-модельные сутки в ускоренном темпе.
+события по ходу модельных суток; сутки идут ускоренно и занимают около двадцати
+четырех минут.
 
 ## Посмотрите сами
 
@@ -47,11 +52,11 @@ ORDER BY EventDate;
 
 Сравните первые восемь дней с восемью строками в [паспорте
 мира](../../data/world-inventory.json): числа совпадут. Дни, сыгранные после
-стартового мира, в паспорте не записаны. Это ожидаемо.
+стартового мира, в паспорте не записаны. Так и задумано.
 
 ## Куда дальше
 
-Глубже генератор разобран в [`generator/`](../../generator/README.md) и в
+Подробнее генератор разобран в [README папки
-[справочнике его устройства](../architecture/generator/README.md). Тропа
+`generator/`](../../generator/README.md) и в [справочнике его
-путеводителя закончена: дальше идут справочники и [учебные
+устройства](../architecture/generator/README.md). На этом путеводитель
-задания](../labs/README.md).
+заканчивается: дальше справочники и [учебные задания](../labs/README.md).

docs/handbook/monitoring.md

@@ -1,49 +1,52 @@
 # Мониторинг: куда смотреть
 
-В Grafana три дашборда, и у каждого свой вопрос. «Данные» спрашивает, все ли в
+В Grafana три дашборда, и у каждого своя тема. «Данные» показывает, все ли в
-порядке с потоком. «Кластер» спрашивает, что с машиной. «Запросы» — что
+порядке с потоком данных. «Кластер» — состояние машин и самого ClickHouse.
-выполнялось и во что обошлось.
+«Запросы» — какие запросы выполнялись и сколько ресурсов они заняли.
 
 Prometheus собирает метрики с двух узлов ClickHouse, keeper и экспортера Kafka.
 Grafana читает и Prometheus, и ClickHouse напрямую. На панелях нет порогов и
-цветовых оценок: на них смотрят глазами. Красное и зеленое живут в проверках и
+цветовой подсветки: оценивать картинку придется самому. Автоматические
-дагах DQ.
+проверки, которые выносят вердикт, собраны в контуре DQ.
 
 ## Дашборд «Данные»
 
-«Свежесть» отвечает, давно ли в ODS появились последние события и заказы.
+«Свежесть» показывает, сколько времени прошло с последнего события и с
-Свежесть заказов растет весь модельный день и падает, когда на границе суток
+последнего заказа в ODS. Свежесть заказов растет весь модельный день и
-приезжает слепок. Так устроен источник, а не сломан стенд.
+сбрасывается, когда на границе суток приходит слепок. Это нормальное поведение
+источника, а не поломка.
 
-«Поток» показывает число сырых сообщений в STG за выбранный интервал. Рядом
+«Поток» показывает число сырых сообщений в STG за выбранный интервал. «Брак»
-«Брак» отвечает, какая часть приехавших строк не прошла разбор.
+рядом — доля строк, которые не удалось разобрать.
 
-«Сходимость» ставит рядом число событий из Kafka и ClickHouse. Ищите устойчивый
+«Сходимость» сравнивает число событий в Kafka и в ClickHouse. Тревожный
-разрыв между линиями: разница в один столбец ничего не значит.
+признак — устойчивый разрыв между линиями. Расхождение в одном столбце ничего
+не значит.
 
-«Отставание» показывает, остались ли у читателей Kafka непрочитанные сообщения.
+«Отставание» показывает, сколько сообщений в Kafka еще не прочитано
-«Дневной слепок» показывает последние десять слепков заказов в STG: по нему
+потребителями. «Дневной слепок» перечисляет последние десять слепков заказов в
-видно, доехала ли выгрузка вовремя.
+STG: по нему видно, пришла ли выгрузка вовремя.
 
 Источники и правила чтения всех панелей разобраны в [справочнике дашборда
 «Данные»](../architecture/monitoring/data.md).
 
-## Почему панели смотрят в разные слои
+## Почему у панелей разные источники
 
-Свежесть спрашивают у ODS: именно там видно, что разбор встал. Поток и брак
+Свежесть считается по ODS: если разбор остановился, это видно именно там. Поток
-считают по STG, где сохраняется каждая доставка. ODS может схлопнуть повтор
+и брак считаются по STG, где сохраняется каждое доставленное сообщение. В ODS
-события или версии заказа и занизить счетчик. Подробности — в [разделе о слоях
+повторы события и старые версии заказа схлопываются, поэтому счетчик там был бы
+занижен. Подробности — в [разделе о слоях
 панелей](../architecture/monitoring/data.md#почему-слои-у-панелей-разные).
 
 ## Два других дашборда
 
-Открывайте «Кластер», когда нужно понять, что происходит с процессором, памятью,
+Открывайте «Кластер», когда нужно понять, что происходит с процессором, памятью
-дисками, частями и слияниями ClickHouse, keeper или очередью DDL. Устройство
+и дисками, с кусками данных и их слияниями в ClickHouse, с keeper или очередью
-панелей описано в [справочнике дашборда
+DDL. Устройство панелей описано в [справочнике дашборда
 «Кластер»](../architecture/monitoring/cluster.md).
 
-«Запросы» нужен, когда вы ищете тяжелые запросы, ошибки или расход ресурсов по
+«Запросы» пригодится, когда вы ищете тяжелые запросы, ошибки или расход
-пользователям. Как читать списки, объясняет [справочник дашборда
+ресурсов по пользователям. Как читать списки, объясняет [справочник дашборда
 «Запросы»](../architecture/monitoring/queries.md).
 
 ## Посмотрите сами
@@ -55,9 +58,9 @@ Airflow [`world_live_day`](airflow-dags.md#даги-мира): модельны
 
 Смотрите свежесть событий и свежесть заказов по отдельности. Пока день идет,
 свежесть событий держится на секундах, а свежесть заказов растет. На границе дня
-слепок уезжает сразу: свежесть заказов падает, а свежесть событий начинает
+слепок отправляется сразу: свежесть заказов сбрасывается, а свежесть событий
-расти. Сам даг остается в работе и после конца дня, потому что ждет дневной
+начинает расти, потому что новых событий до следующего дня не будет. Сам даг
-конвейер.
+остается в работе и после конца дня, потому что ждет дневной конвейер.
 
 ## Куда дальше
 

docs/handbook/superset.md

@@ -1,7 +1,8 @@
 # Немного Superset
 
-Superset — это витрины глазами. Он читает слой DM пользователем `bi`. На
+Superset показывает витрины слоя DM в виде графиков. К ClickHouse он
-дашборде стенда «Бизнес-сюжеты» три графика:
+подключается пользователем `bi`. На дашборде стенда «Бизнес-сюжеты» три
+графика:
 
 | График | Витрина |
 |---|---|
@@ -11,26 +12,30 @@ Superset — это витрины глазами. Он читает слой DM
 
 ## Как витрина становится графиком
 
-Путь состоит из трех объектов: датасет → график → дашборд. Датасет описывает
+От витрины до экрана три объекта Superset: датасет → график → дашборд. Датасет
-витрину: он несет русские имена колонок и формат денег. График ссылается на эти
+описывает витрину: задает русские имена колонок и формат денег. График
-имена и задает способ показа. Дашборд собирает готовые графики на одном экране.
+ссылается на эти имена и задает способ показа. Дашборд собирает готовые графики
+на одном экране.
 
-## Свое и стендовое
+## Стендовые объекты и ваши
 
-Стендовые объекты приезжают из файлов при каждом `make up`. Правка такого
+Датасеты, графики и дашборд из поставки стенда лежат файлами в репозитории и
-датасета, графика или дашборда в интерфейсе живет до следующей инициализации, а
+заново импортируются при каждом `make up`. Если поправить такой объект в
-затем молча заменяется версией из репозитория.
+интерфейсе, правка проживет до следующего `make up`, а потом без предупреждения
+заменится версией из файла.
 
-Ваши объекты живут рядом в базе метаданных Superset. Они переживают `make up` и
+Ваши собственные объекты хранятся в той же базе метаданных Superset, но импорт
-`make rebuild-storage`. Только `make clean` стирает их вместе с остальным
+их не трогает: они переживают и `make up`, и `make rebuild-storage`. Стирает их
-постоянным состоянием стенда. Поэтому стендовые объекты оставляйте как есть, а
+только `make clean` вместе с остальным постоянным состоянием стенда. Поэтому
-свои отчеты стройте рядом. Устройство импорта описано в [справочнике
+стендовые объекты оставляйте как есть, а свои отчеты стройте рядом. Устройство
+импорта описано в [справочнике
 Superset](../architecture/superset.md#импорт-при-каждой-инициализации).
 
 ## Почему края графиков не совпадают
 
-Правый край выручки всегда на день позади кликстрима. Слепок заказов дня
+Правый край графика выручки всегда на день позади графиков кликстрима. Слепок
-приезжает со следующим ходом мира. Так устроен источник. Вы уже видели этот
+заказов за день приходит только со следующим модельным днем. Так устроен
+источник, а не витрина. Вы уже видели этот
 сдвиг в [главе об Airflow](airflow-dags.md#посмотрите-сами). Начальное состояние
 показано в разделе [«Стартовый мир»](../architecture/world.md#стартовый-мир).