docs(project): добавлены PRD и ADR для сайта de-roadmap

- Зачем: - зафиксировать проектные решения до начала реализации. - Что: - добавлен project/PRD.md — требования, цели, итерации и риски. - добавлен project/ADR.md — выбор MkDocs Material, структура файлов, стратегия dual-compatible ссылок, конфиг CI/CD. - Проверка: - файлы читаемы на GitHub: project/PRD.md и project/ADR.md.
2026-03-25 23:38:34 +03:00
parent 2967664e43
commit 721ed4163b
2 changed files with 518 additions and 0 deletions
@@ -0,0 +1,350 @@
 # ADR: Архитектура сайта de-roadmap
 > Архитектурный документ. Проектные цели и требования — в [PRD](./PRD.md).
 ---
 ## 1. Ключевые архитектурные требования
 Из PRD вытекают четыре жёстких ограничения, определяющих выбор инструментов:
 1. **Сайт опционален.** Репозиторий должен полноценно работать без сайта. Удалили конфиг — всё как было.
 2. **Dual-compatible links.** Внутренние ссылки между `.md` файлами должны работать и на GitHub, и на сайте.
 3. **Один файл = один источник правды.** Не должно быть копий или генерируемых `.md`. Редактируем один раз — рендерится везде.
 4. **Zero-effort deploy.** Push в `main` → сайт обновился. Без ручных шагов, без локальной сборки.
 ---
 ## 2. Выбор генератора статического сайта
 ### Рассмотренные варианты
 | Критерий | MkDocs Material | Docusaurus | Hugo | Astro |
 |----------|----------------|------------|------|-------|
 | Язык/экосистема | Python | Node.js (React) | Go | Node.js |
 | Порог входа | Минимальный — `pip install`, один YAML | Средний — npm, React-компоненты | Средний — Go templates | Высокий — фреймворк |
 | Поддержка Markdown «как есть» | Отличная, расширения через плагины | Хорошая, но MDX-ориентирован | Хорошая, но shortcodes вместо стандартного MD | Хорошая |
 | Навигация по длинной странице | TOC sidebar из коробки | Есть, но заточен под многостраничность | Зависит от темы | Зависит от темы |
 | Поиск | Встроенный (lunr.js), работает offline | Algolia (внешний сервис) или плагин | Нет из коробки | Нет из коробки |
 | Тёмная тема | Из коробки, переключатель | Из коробки | Зависит от темы | Зависит от темы |
 | GitHub Pages деплой | Одна команда / готовый Action | Готовый Action | Готовый Action | Готовый Action |
 | Dual-compatible links | Поддерживает с настройкой `use_directory_urls` | Преобразует ссылки, может ломать GitHub | Преобразует ссылки | Преобразует ссылки |
 | Один мейнтейнер, Python-стек | ✅ Идеально | ❌ Node.js | ⚠️ Go, но бинарник | ❌ Node.js |
 ### Решение: MkDocs Material
 **Почему:**
 - Python-based — совпадает со стеком автора, `pip install` и готово.
 - Лучшая из коробки поддержка длинных страниц с TOC — именно наш сценарий.
 - Встроенный поиск без внешних сервисов.
 - Самый простой конфиг — один `mkdocs.yml`.
 - Крупнейшее комьюнити среди генераторов документации, активно развивается.
 - Dual-compatible links решаемы (см. раздел 4).
 **Почему не Docusaurus:** Node.js-зависимость, ориентирован на многостраничные доки с MDX-компонентами — overkill для «красивый рендер Markdown». Преобразование ссылок может конфликтовать с GitHub-форматом.
 **Почему не Hugo:** Быстрый, но Go-шаблоны сложнее отлаживать. Нет встроенного поиска. Для нашего объёма контента скорость сборки не критична.
 **Почему не Astro:** Полноценный веб-фреймворк — избыточен. Подошёл бы, если бы мы строили маркетинговый сайт с интерактивом, но это не текущая цель.
 ---
 ## 3. Структура файлов
 ### Решение открытого вопроса: `docs/` vs корень репо
 **Решение: `docs_dir: .` (корень репо = корень сайта), с исключениями.**
 Причина: не создаём отдельную папку `docs/`, не дублируем и не перемещаем файлы. MkDocs умеет работать с корнем репо как источником, исключая ненужное.
 ```yaml
 # mkdocs.yml (в корне репо)
 docs_dir: .
 ```
 ### Решение открытого вопроса: README.md как index
 **Решение: плагин `awesome-pages` или конфигурация `nav` с явным указанием.**
 MkDocs по умолчанию ищет `index.md`. Но мы хотим сохранить `README.md` (GitHub его рендерит на главной репо). Есть два пути:
 - **Вариант A:** Симлинк `docs/index.md → ../README.md`. Но мы не используем `docs/`.
 - **Вариант B (выбран):** В `mkdocs.yml` явно указать `README.md` как главную:
 ```yaml
 nav:
  - Роадмап: README.md
  - Моделирование данных:
    - Введение: dwh-modeling/README.md
    - SCD: dwh-modeling/SCD.md
    - Data Vault: dwh-modeling/DataVault.md
    - "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
 ```
 MkDocs Material корректно обрабатывает `README.md` файлы — рендерит их как `index.html` соответствующей директории.
 ### Исключения из сборки
 Файлы и папки, которые не должны попасть на сайт:
 ```yaml
 exclude_docs: |
  project/          # проектная документация (PRD, ADR)
  postgres-bookings/ # скрипты стенда (не контент сайта)
  AGENTS.md         # конфигурация для AI-агентов
  LICENSE           # лицензия (есть в footer)
  .gitignore
 ```
 ### Итоговая структура репо
 ```
 de-roadmap/
 ├── mkdocs.yml              ← конфиг сайта (единственный новый файл в корне)
 ├── README.md               ← главная страница сайта И главная страница GitHub
 ├── dwh-modeling/
 │   ├── README.md           ← подстраница «Введение в DWH»
 │   ├── SCD.md              ← подстраница
 │   ├── DataVault.md        ← подстраница
 │   └── Homework_*.md       ← подстраница
 ├── postgres-bookings/      ← исключён из сайта
 ├── project/                ← PRD, ADR — исключены из сайта
 │   ├── PRD.md
 │   └── ADR.md
 ├── .github/
 │   └── workflows/
 │       └── deploy-site.yml ← CI/CD pipeline
 ├── AGENTS.md               ← исключён из сайта
 └── LICENSE
 ```
 ---
 ## 4. Стратегия ссылок (Dual Compatibility)
 ### Проблема
 GitHub рендерит ссылки вида `[текст](dwh-modeling/SCD.md)` как переход к файлу.
 MkDocs по умолчанию преобразует `.md` → `.html` и может менять структуру URL.
 ### Решение
 Комбинация настроек MkDocs:
 ```yaml
 use_directory_urls: true  # /dwh-modeling/SCD/ вместо /dwh-modeling/SCD.html
 ```
 И ссылки в Markdown пишем **всегда как относительные пути к `.md` файлам**:
 ```markdown
 <!-- Это работает и на GitHub, и в MkDocs -->
 [Теория про SCD](dwh-modeling/SCD.md)
 [Введение в DWH](dwh-modeling/README.md)
 ```
 MkDocs Material автоматически резолвит `.md` ссылки в правильные URL сайта.
 ### Кириллические якоря
 GitHub генерирует якоря из кириллических заголовков с URL-encoding:
 `## Базы данных` → `#базы-данных`
 MkDocs Material по умолчанию делает то же самое через расширение `toc`:
 ```yaml
 markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
      permalink: true
 ```
 **Риск:** поведение может различаться на edge cases (спецсимволы, эмодзи в заголовках). Митигация — на этапе MVP протестировать все существующие якорные ссылки в README.
 ---
 ## 5. CI/CD Pipeline
 ### GitHub Actions Workflow
 ```yaml
 # .github/workflows/deploy-site.yml
 name: Deploy MkDocs to GitHub Pages
 on:
  push:
    branches: [main]
  workflow_dispatch:  # ручной запуск для отладки
 permissions:
  contents: read
  pages: write
  id-token: write
 concurrency:
  group: "pages"
  cancel-in-progress: false
 jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material
      - run: mkdocs build --strict
        # --strict: падает на warnings (битые ссылки, отсутствующие файлы)
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site/
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4
 ```
 ### Что даёт `--strict`
 Сборка упадёт, если:
 - Есть ссылка на несуществующий `.md` файл.
 - Есть битый якорь.
 - Есть warning от MkDocs.
 Это наш автотест ссылок — бесплатно, в CI.
 ---
 ## 6. Конфигурация MkDocs Material
 ### Минимальный `mkdocs.yml` для MVP
 ```yaml
 site_name: "DE Roadmap — Data Engineering с нуля до middle"
 site_url: https://dementev-dev.github.io/de-roadmap/
 site_description: "Роадмап по Data Engineering: SQL, Python, Airflow, Greenplum и далее"
 site_author: Dmitry Dementev
 repo_url: https://github.com/dementev-dev/de-roadmap
 repo_name: dementev-dev/de-roadmap
 docs_dir: .
 site_dir: site
 # Исключаем из сборки
 exclude_docs: |
  project/
  postgres-bookings/
  AGENTS.md
  LICENSE
  .gitignore
  .github/
  site/
 nav:
  - Роадмап: README.md
  - Моделирование данных:
    - Введение: dwh-modeling/README.md
    - SCD: dwh-modeling/SCD.md
    - Data Vault: dwh-modeling/DataVault.md
    - "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
 theme:
  name: material
  language: ru
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Тёмная тема
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Светлая тема
  features:
    - navigation.top          # кнопка «наверх»
    - navigation.tracking     # URL обновляется при скролле
    - search.suggest          # подсказки в поиске
    - search.highlight        # подсветка найденного
    - toc.follow              # TOC следит за скроллом
    - content.code.copy       # кнопка копирования кода
 markdown_extensions:
  - toc:
      permalink: true
  - admonition                # сворачиваемые блоки (Спринт 2)
  - pymdownx.details          # для <details>
  - pymdownx.superfences      # вложенные блоки кода
  - pymdownx.highlight        # подсветка синтаксиса
  - attr_list                 # атрибуты для элементов
 plugins:
  - search:
      lang: ru
 ```
 ### Что уже включено в MVP (бесплатно с Material)
 - Тёмная/светлая тема с переключателем.
 - Полнотекстовый поиск на русском.
 - TOC (оглавление) в правом sidebar.
 - Кнопка «наверх» на длинной странице.
 - URL обновляется при скролле (можно дать ссылку на конкретный раздел).
 - Подсветка синтаксиса в блоках кода.
 - Кнопка копирования кода.
 - Ссылка на GitHub-репозиторий в шапке.
 ---
 ## 7. Кастомный домен (Спринт 2)
 Домен `dementev.space` уже есть. Для подключения:
 1. Создать CNAME-запись: `roadmap.dementev.space → dementev-dev.github.io`.
 2. Добавить файл `CNAME` в корень репо с содержимым `roadmap.dementev.space`.
 3. В `mkdocs.yml` обновить `site_url`.
 4. Включить HTTPS в настройках GitHub Pages.
 ---
 ## 8. Риски и митигации
 | Риск | Митигация |
 |------|-----------|
 | `docs_dir: .` подхватывает лишние файлы | `exclude_docs` со списком исключений; `--strict` ловит проблемы |
 | Кириллические якоря ведут себя по-разному | Тестируем все якорные ссылки из README при первом деплое |
 | `README.md` содержит GitHub-специфичный синтаксис | Проверяем рендер; при необходимости используем MkDocs-совместимые альтернативы |
 | Зависимость от `mkdocs-material` | Активный проект (30k+ stars), Python-пакет; при необходимости — заморозить версию в `requirements.txt` |
 | `exclude_docs` — относительно новая фича MkDocs | Альтернатива: `.mkdocsignore` или плагин `mkdocs-exclude`; протестировать на MVP |
 ---
 ## 9. Порядок действий (Спринт 1)
 1. Создать ветку `feature/site`.
 2. Добавить `mkdocs.yml` в корень репо.
 3. Добавить `.github/workflows/deploy-site.yml`.
 4. Добавить `project/PRD.md` и `project/ADR.md`.
 5. Проверить локально: `pip install mkdocs-material && mkdocs serve`.
 6. Протестировать все внутренние ссылки и якоря.
 7. При необходимости — адаптировать ссылки для dual compatibility.
 8. Merge в `main` → автодеплой → проверить `https://dementev-dev.github.io/de-roadmap/`.
 9. Включить GitHub Pages (Settings → Pages → Source: GitHub Actions).
@@ -0,0 +1,168 @@
 # PRD: Сайт для de-roadmap
 > Проектный документ. Техническая архитектура — в отдельном ADR.
 ---
 ## 1. Контекст и мотивация
 ### Текущее состояние
 Роадмап по Data Engineering живёт как GitHub-репозиторий ([dementev-dev/de-roadmap](https://github.com/dementev-dev/de-roadmap)):
 - Основной контент — монолитный `README.md` (~700 строк) с полным учебным планом.
 - Дополнительные материалы — в подпапках (`dwh-modeling/`, `postgres-bookings/`): теория DWH-моделирования, SCD, Data Vault, домашние задания, скрипты.
 - 109 коммитов, контент активно развивается.
 - Основной поток менти приходит через маркетплейс ОМ (Осознанная Меркантильность) — платформу менторства с системой отзывов, ранжированием менторов и модерацией. Участие платное (абонентская плата + аукцион за позицию в выдаче).
 - Роадмап изначально создавался для себя — как конспект подходов к обучению. Со временем стал использоваться и для менти (удобная структура прохождения), и на ознакомительных созвонах с лидами из ОМ (демонстрация программы и подхода к обучению).
 - Отдельного маркетингового продвижения роадмапа не было, органических приходов «по ссылке из интернета» — ноль. Сайта ментора тоже пока нет — приходить некуда.
 ### Проблема
 GitHub README — рабочий, но не презентабельный формат:
 - Нет удобной навигации по длинному документу (только ручной скролл или оглавление-ссылки).
 - Выглядит как «техническая документация», а не как продукт ментора.
 - GitHub README плохо индексируется поисковыми системами — роадмап в таком виде даже потенциально не может привлекать органический трафик и «продавать сам себя».
 - Неудобно давать ссылку потенциальному менти — GitHub-интерфейс отвлекает (issues, commits, файловое дерево).
 - Нет мобильной адаптации контента (GitHub на телефоне — страдание).
 ### Чего НЕ решаем этим проектом
 - **Лидогенерацию и воронку продаж.** Основной поток тёплых лидов идёт через маркетплейс ОМ, и конкурировать с ним по объёму нереалистично — даже топовые менторы не добирают сравнимое количество лидов из других источников. В перспективе сайт может стать элементом маркетинговой воронки (Habr → сайт → менторство), но это отдалённая цель, не влияющая на текущие решения. Сейчас сайт — витрина экспертизы, а не маркетинговый инструмент.
 - **Масштабирование менторского бизнеса.** Сейчас приоритет — выпустить текущих менти, а не набрать новых.
 - **Создание LMS / интерактивного курса.** Формат остаётся «структурированный текст + ссылки», без трекинга прогресса и автопроверок.
 ---
 ## 2. Цели
 | # | Цель | Метрика успеха |
 |---|------|----------------|
 | 1 | Удобная читаемая версия роадмапа | Сайт с навигацией, поиском, мобильной версией |
 | 2 | Репозиторий остаётся полностью рабочим без сайта | Все `.md` файлы читаемы на GitHub, ссылки между ними работают |
 | 3 | Минимальные накладные расходы на поддержку | Обновил `.md` → запушил → сайт обновился автоматически |
 | 4 | Презентабельный вид для демонстрации на созвонах | Ссылка, которую удобно показать лиду из ОМ при обсуждении программы |
 ---
 ## 3. Целевая аудитория
 **Основная:** менти (текущие и потенциальные) — джуны и переходящие в DE из смежных областей. Приходят по рекомендации из ОМ или по прямой ссылке от ментора. Им нужно быстро оценить объём программы и найти нужный раздел.
 **Вторичная:** коллеги-инженеры, которые наткнулись на репозиторий через GitHub/поиск. Для них важна полнота контента и техническая достоверность, а не «продающие» элементы.
 ---
 ## 4. Требования
 ### 4.1. Обязательные (MVP)
 **Контент и структура:**
 - [ ] Главная страница сайта = полный текст текущего `README.md` (одна длинная страница, не разбиваем).
 - [ ] Подстраницы из существующих `.md` файлов (`dwh-modeling/README.md`, `SCD.md`, `DataVault.md`, домашки).
 - [ ] Автоматическое оглавление (Table of Contents) по заголовкам H2/H3 на главной странице.
 - [ ] Внутренние ссылки работают и на GitHub, и на сайте (dual-compatible links).
 **Навигация:**
 - [ ] Боковая панель с разделами сайта (основной README + подразделы).
 - [ ] Оглавление текущей страницы (правый sidebar / TOC).
 - [ ] Полнотекстовый поиск по сайту.
 **Деплой:**
 - [ ] Автоматическая сборка и публикация при пуше в `main`.
 - [ ] Бесплатный хостинг (GitHub Pages).
 **Совместимость с репо:**
 - [ ] Все `.md` файлы остаются читаемыми на GitHub «как есть».
 - [ ] `README.md` в корне репо продолжает рендериться на главной странице репозитория.
 - [ ] Добавление сайта не ломает существующую структуру — если удалить конфиг сайта, репо работает как раньше.
 ### 4.2. Желательные (Спринт 2+)
 - [ ] Кастомный домен (например, `roadmap.dementev.space`).
 - [ ] Тёмная тема (переключатель light/dark).
 - [ ] Сворачиваемые блоки (collapsible sections / admonitions) для длинных списков материалов.
 - [ ] Кнопка «Написать в Telegram» (floating или в footer) — не агрессивный CTA, просто удобство.
 - [ ] Иконки/бейджи для статуса разделов (пройден / в процессе / не начат) — пока декоративные, без бэкенда.
 - [ ] Яндекс.Метрика или аналогичная аналитика (понимать, сколько людей заходят).
 ### 4.3. Явно НЕ делаем
 - Разбивку основного README на отдельные страницы.
 - Интерактивный трекинг прогресса менти.
 - Систему авторизации / личный кабинет.
 - Блог или раздел новостей (для этого есть Telegram-канал).
 - SEO-оптимизацию и маркетинговые landing pages.
 ---
 ## 5. Ограничения
 - **Бюджет: 0 ₽** (кроме домена, если решим подключить кастомный — `dementev.space` уже есть).
 - **Время на поддержку: минимальное.** Рабочий процесс = «редактирую `.md` → push → сайт обновляется». Не должно быть отдельного шага сборки, ручного деплоя или npm-зависимостей, требующих обновления.
 - **Стек автора: Python-first.** Решение на Python-тулинге предпочтительнее, чем на Node.js/Ruby (проще отлаживать при необходимости).
 - **Один мейнтейнер.** Сайт поддерживает один человек — сложность решения должна быть соответствующей.
 ---
 ## 6. Итерации
 ### Спринт 1 — MVP: «Сайт, который просто работает»
 **Scope:**
 - Конфигурация генератора статического сайта.
 - CI/CD pipeline (GitHub Actions → GitHub Pages).
 - Главная страница = README.
 - Подстраницы из `dwh-modeling/`.
 - Фикс внутренних ссылок для dual compatibility.
 **Definition of Done:**
 - Сайт доступен по URL `https://dementev-dev.github.io/de-roadmap/`.
 - Все ссылки внутри README работают и на сайте, и на GitHub.
 - При пуше в `main` сайт автоматически пересобирается за < 2 минут.
 - Контент на GitHub выглядит ровно так же, как до добавления сайта.
 ### Спринт 2 — «Удобство и навигация»
 **Scope:**
 - Кастомный домен.
 - Тёмная тема.
 - Сворачиваемые блоки для длинных секций.
 - Кнопка «Написать ментору» (Telegram).
 - Базовая аналитика.
 ### Спринт 3 — «Контент и визуал» (по необходимости)
 **Scope:**
 - Визуальная карта роадмапа (интерактивная диаграмма прохождения).
 - Страница «О менторе» / «Отзывы выпускников» (когда будут выпускники).
 - Расширение контента: новые разделы роадмапа → автоматически появляются на сайте.
 ---
 ## 7. Риски
 | Риск | Вероятность | Влияние | Митигация |
 |------|-------------|---------|-----------|
 | Ссылки ломаются при конвертации (GitHub vs сайт) | Средняя | Высокое | Стратегия dual-compatible links в ADR; автотест ссылок в CI |
 | Кириллические якоря рендерятся по-разному | Средняя | Среднее | Тестирование конкретного генератора; при необходимости — латинские id |
 | Генератор сайта перестаёт поддерживаться | Низкая | Среднее | Контент в plain Markdown — миграция на другой генератор за день |
 | Накладные расходы на поддержку растут | Низкая | Среднее | Принцип «сайт опционален»: если мешает — удаляем конфиг, репо работает |
 | GitHub Pages ограничения (bandwidth, размер) | Очень низкая | Низкое | Для статического сайта с текстом — не актуально |
 ---
 ## 8. Открытые вопросы
 1. **Домен.** Использовать GitHub Pages URL или сразу подключить кастомный домен? Можно решить в Спринте 2.
 2. **README.md в корне vs docs/.** Оставляем README.md в корне (GitHub его рендерит) и используем его же как `index.md` для сайта, или делаем симлинк / копию? → Решение в ADR.
 3. **Структура `docs/` директории.** Нужно ли вообще создавать `docs/`, или генератор может работать прямо с корнем репо? → Решение в ADR.