Постановка учебной документации стенда #208

New Issue

2026-09-01T16:50:49+03:00

ddmitry commented

2026-09-01 16:50:49 +03:00

Part of #206

Вопрос

Развилка первого тикета карты: в какой форме и с какой структурой писать учебную документацию стенда.

Форма: markdown в репозитории или HTML (образцы оформления — скилл /teach)?
Структура и состав: базовый README для менти; архитектура решений глазами учащегося — на что смотреть в первую очередь и почему так сделано; упор на хранилище и потоки Airflow, пояснение мониторинга и немного BI; генератор — только в общих словах.

Решается веером с владельцем (brainstorm-with-docs): сначала веер вариантов, потом конвергенция. Итог тикета — принятая форма и структура плюс постановка работ по написанию: самодостаточные задания со своими исполнителями (проза для людей — Sol, вкусовые решения — Fable, техническая беготня — Codex).

Part of #206 ## Вопрос Развилка первого тикета карты: в какой форме и с какой структурой писать учебную документацию стенда. - **Форма**: markdown в репозитории или HTML (образцы оформления — скилл /teach)? - **Структура и состав**: базовый README для менти; архитектура решений глазами учащегося — на что смотреть в первую очередь и почему так сделано; упор на хранилище и потоки Airflow, пояснение мониторинга и немного BI; генератор — только в общих словах. Решается веером с владельцем (brainstorm-with-docs): сначала веер вариантов, потом конвергенция. Итог тикета — принятая форма и структура плюс постановка работ по написанию: самодостаточные задания со своими исполнителями (проза для людей — Sol, вкусовые решения — Fable, техническая беготня — Codex).

ddmitry added the wayfinder:grilling label 2026-09-01 16:50:58 +03:00

ddmitry self-assigned this 2026-09-01 16:50:58 +03:00

ddmitry referenced this issue

2026-09-01 16:51:00 +03:00

Реализация учебной программы: документация стенда и ТЗ лаб #206

ddmitry commented

2026-09-01 20:41:32 +03:00

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

Форма — три части

Корневой README получает человеческую шапку: что это такое, как поднять и выключить, что с этим делать — и ссылка на уроки. Точечный пересмотр; операторские разделы остаются, просто перестают быть первым, что видит новичок.
Учебная документация — markdown в репозитории: читается по ссылкам прямо в Gitea. Простые диаграммы — mermaid или готовый SVG.
Интерактивная карта архитектуры — один самодостаточный HTML-файл: скачал — открыл откуда угодно, в том числе из синхронизированной копии репозитория. В репозитории живут и исходники карты, и готовый файл как их рендер: правится исходник, файл пересобирается.

Структура — папка-путеводитель `docs/handbook/`

README.md — вход и порядок чтения: тропа глоссарий → архитектура → уроки.
Главы «глазами учащегося»: хранилище и его слои; потоки Airflow и пульт мира; мониторинг — куда смотреть; немного Superset; генератор одной страницей «откуда берутся данные».
Главы ведут в справочники docs/architecture/, а не пересказывают их. Детализация до колонок при этом уместна там, где менти будет её искать: ключи, по которым слои соединяются. Состав стенда почти заморожен — стенд сделан как пособие и меняется только по существенной надобности; если DDL всё же меняется, путеводитель обновляется тем же PR — общее правило репозитория.
Интерактивная карта живёт в той же папке. Охват первой версии — слои хранилища и путь данных через них; потоки Airflow — вторым слоем карты, если первая приживётся.

Кто пишет

По правилу карты: русская проза для людей — Sol (gpt-5.6-sol, через Codex-конвейер); вкусовые решения — состав, имена, границы — Fable; техническая беготня — сбор фактов из кода, рендер карты, проверка ссылок — Codex. Вкусовая часть идёт первой: скелет задаёт форму. Финальные фильтры прозы: writing-for-agents при постановке, ai-text-lint плюс оптика литературного русского на приёмке.

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

Крупным зерном, без нарезки впрок (тикеты появляются по одному при старте): скелет путеводителя и README-шапка → главы → интерактивная карта. Первый рабочий тикет откроется следующей сессией.

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

HTML-учебник по образцу /teach — второй корпус документации, который не обновляется вместе с кодом и молча протухает; сам /teach устроен под живые сессии с конкретным менти (миссия, записи обучения), а не под статичную документацию стенда — там он и пригодится.
Гибрид: вся документация в markdown с HTML-рендером — свой конвейер сборки ради типографики; менти платит вопросом, получает шрифты.
Учебные врезки внутри справочников docs/architecture/ — размывает жанр справочника, а тропы для менти всё равно не даёт.
Только README-надстройка, без глав — поручение карты «на что смотреть в первую очередь и почему так сделано» остаётся неписаным.

Резолюция принята владельцем в живом обсуждении. ## Форма — три части 1. **Корневой README** получает человеческую шапку: что это такое, как поднять и выключить, что с этим делать — и ссылка на уроки. Точечный пересмотр; операторские разделы остаются, просто перестают быть первым, что видит новичок. 2. **Учебная документация — markdown в репозитории**: читается по ссылкам прямо в Gitea. Простые диаграммы — mermaid или готовый SVG. 3. **Интерактивная карта архитектуры — один самодостаточный HTML-файл**: скачал — открыл откуда угодно, в том числе из синхронизированной копии репозитория. В репозитории живут и исходники карты, и готовый файл как их рендер: правится исходник, файл пересобирается. ## Структура — папка-путеводитель `docs/handbook/` - `README.md` — вход и порядок чтения: тропа глоссарий → архитектура → уроки. - Главы «глазами учащегося»: хранилище и его слои; потоки Airflow и пульт мира; мониторинг — куда смотреть; немного Superset; генератор одной страницей «откуда берутся данные». - Главы ведут в справочники `docs/architecture/`, а не пересказывают их. Детализация до колонок при этом уместна там, где менти будет её искать: ключи, по которым слои соединяются. Состав стенда почти заморожен — стенд сделан как пособие и меняется только по существенной надобности; если DDL всё же меняется, путеводитель обновляется тем же PR — общее правило репозитория. - Интерактивная карта живёт в той же папке. Охват первой версии — слои хранилища и путь данных через них; потоки Airflow — вторым слоем карты, если первая приживётся. ## Кто пишет По правилу карты: русская проза для людей — Sol (gpt-5.6-sol, через Codex-конвейер); вкусовые решения — состав, имена, границы — Fable; техническая беготня — сбор фактов из кода, рендер карты, проверка ссылок — Codex. Вкусовая часть идёт первой: скелет задаёт форму. Финальные фильтры прозы: writing-for-agents при постановке, ai-text-lint плюс оптика литературного русского на приёмке. ## Очередь работ Крупным зерном, без нарезки впрок (тикеты появляются по одному при старте): скелет путеводителя и README-шапка → главы → интерактивная карта. Первый рабочий тикет откроется следующей сессией. ## Отклонённые варианты - **HTML-учебник по образцу /teach** — второй корпус документации, который не обновляется вместе с кодом и молча протухает; сам /teach устроен под живые сессии с конкретным менти (миссия, записи обучения), а не под статичную документацию стенда — там он и пригодится. - **Гибрид: вся документация в markdown с HTML-рендером** — свой конвейер сборки ради типографики; менти платит вопросом, получает шрифты. - **Учебные врезки внутри справочников `docs/architecture/`** — размывает жанр справочника, а тропы для менти всё равно не даёт. - **Только README-надстройка, без глав** — поручение карты «на что смотреть в первую очередь и почему так сделано» остаётся неписаным.

ddmitry closed this issue

2026-09-01 20:41:33 +03:00

ddmitry referenced this issue

2026-09-01 20:52:20 +03:00

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

ddmitry referenced this issue

2026-09-01 21:35:33 +03:00

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

ddmitry referenced this issue

2026-09-02 22:37:52 +03:00

Пересборка корневого README: четыре блока и адресация читателя #216

ddmitry referenced this issue