Формат проекта

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

Из чего состоит сайт

• Верхнеуровневая mermaid-схема ветвей — в README.md на GitHub.
• Интерактивный паук (главная страница) и branch-views — рендерятся на сайте из src/data/roadmap.ts.
• Содержимое каждого листа — на сайте по адресу /The-Way-of-SRE/<branch>/<slug>/, рядом с hub-страницами L1 той же ветви; исходники в src/content/docs/<branch>/<slug>.md.
• Шаблон листа — inventory/leaf-template.md в репозитории.

Структура листа

Каждый лист идёт по единому шаблону:

1. Lead-параграф — начинается с мнения автора / диагноза проблемы / конкретного случая. От первого лица. Не пересказ description.
2. Метаданные листа — ветвь, путь в графе, SFIA-уровни, приоритет, статус. Руками не пишутся: блок рендерится под заголовком из src/data/roadmap.ts, а в самом листе лежат только sfia и status во frontmatter.
3. Что должен уметь — формулировки уровня «умеет N», привязанные к диапазону SFIA-уровней. Перед списком — короткая проза с приоритизацией («главный навык на уровне LX — …»).
4. Материалы — внешние источники с личной оценкой минимум для половины: «по моим наблюдениям, чаще выбирают X»; «если выбирать одну главу — эту».
5. Best practices — не больше половины в шаблоне «утверждение/антипаттерн/правильно»; остальное прозой с авторским голосом. Опционально — открывающий параграф с конкретным публичным кейсом (GitLab 2017, Cloudflare 2019, log4shell, Netflix Chaos Monkey, DORA Accelerate).
6. Связанные листья — с типом связи (предпосылка / продолжение / альтернатива). Коротко.
7. Открытые вопросы — опционально, для листьев в статусе draft. Допускается «я не разобрался с X» как приглашение к PR.

Подробные правила заполнения шаблона — в файле inventory/leaf-template.md. Шаблон лежит вне каталога контента и на сайт не попадает.

Голос и терминология

Контент пишется от первого лица как наблюдение профессионала: «я регулярно вижу», «по моим наблюдениям», не «команды должны». Мнения — через наблюдение, не через категоричный выбор: «я вижу, что чаще выбирают X», не «я бы выбрал X».

В каждом листе обязательны: один конкретный пример (публичный incident или авторское наблюдение), одно явное мнение, одна граница применимости.

Терминология: устоявшиеся англицизмы SRE (SLI/SLO, postmortem, runbook, on-call, blameless) пишутся латиницей курсивом без склонения. Явные кальки (decision log, shift transition, sitrep cadence) переводятся. Запрещены гибриды через дефис («blameless-принцип», «high-severity incident», «pull-based модель»).

Полные правила и определения живут в двух разных местах:

• Глоссарий — публичный артефакт читателя. Что термин значит: определение, перевод, категория, ссылки на листья, источник. Если в листе встречается термин — он сначала ищется и при необходимости добавляется в глоссарий, прежде чем уйти в текст листа.
• inventory/style-guide.md — внутренний документ контрибутора. Голос, структура секций, запрещённые AI-паттерны, чеклист готовности.
• inventory/terminology.md — внутренний документ контрибутора. Как переводить термины: 4 категории (оставляем латиницей / переводим / двойная форма / спорные), правила графики.

Источники структуры

Файл	За что отвечает
src/data/roadmap.ts	L1-узлы каждой ветви, priorities L1, leaves под L1 и их подлисты
src/content/docs/{culture,engineering,practices}.mdx	Обзор ветви: интро и карта
src/content/docs/<branch>/<l1-id>.mdx	Описание одного L1 прозой; L2 и практики рендерятся из данных
src/content/docs/<branch>/<slug>.md	Содержимое одного листа
inventory/overlaps.md (GitHub)	Решения по пересечениям между ветвями (рабочий артефакт)

Подробнее про инварианты — в Методологии.

Как контрибутить

• Поправки в листьях — PR с одним атомарным изменением в одном файле.
• Изменения в структуре графа (L1 и инвентарь L2 в src/data/roadmap.ts) — обязательно сверка с Методологией и inventory/overlaps.md в репозитории. Новый L1 — это запись в roadmap.ts с непустым l2 плюс страница src/content/docs/<branch>/<l1-id>.mdx; без страницы make check не пройдёт.
• Новые листья — создаются строго по шаблону inventory/leaf-template.md в src/content/docs/<branch>/<slug>.md и регистрируются в src/data/roadmap.ts. Сайдбар строится из этих данных, править его руками не нужно.
• Точка подключения листа. Лист вешается под L1, если это самостоятельная практика раздела. Если он уточняет уже написанную практику — вешается в её поле children (Runbooks → Playbooks). Уровень уточнений один: под подлистом детей быть не может, и попытка их завести не пройдёт bun run check. Признак, что уточнение просится глубже, — родитель дорос до L1 и повышается. Подлист живёт в той же ветви, что и родитель, приоритет у него собственный, а URL остаётся плоским (/<branch>/<slug>/), поэтому перевесить лист можно одной строкой без редиректов.
• Обсуждение — Чат в Telegram, новые листья и анонсы — в Канале.