de-roadmap/project/PRD.md

# 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)

**Контент и структура:**

- [x] Главная страница сайта = полный текст текущего `README.md` (одна длинная страница, не разбиваем).
- [x] Подстраницы из существующих `.md` файлов (`dwh-modeling/README.md`, `SCD.md`, `DataVault.md`, домашки).
- [x] Автоматическое оглавление (Table of Contents) по заголовкам H2/H3 на главной странице.
- [x] Внутренние ссылки работают и на GitHub, и на сайте (dual-compatible links).

**Навигация:**

- [x] Боковая панель с разделами сайта (основной README + подразделы).
- [x] Оглавление текущей страницы (правый sidebar / TOC).
- [x] Полнотекстовый поиск по сайту.

**Деплой:**

- [x] Автоматическая сборка и публикация при пуше в `main`.
- [x] Бесплатный хостинг (GitHub Pages).

**Совместимость с репо:**

- [x] Все `.md` файлы остаются читаемыми на GitHub «как есть».
- [x] `README.md` в корне репо продолжает рендериться на главной странице репозитория.
- [x] Добавление сайта не ломает существующую структуру — если удалить конфиг сайта, репо работает как раньше.

### 4.2. Желательные (Спринт 2+)

- [x] Кастомный домен: `de.dementev.space` (подключён 2026-03-27).
- [x] Тёмная тема (переключатель light/dark).
- [x] Сворачиваемые блоки (`<details>`) — точечно, для подсказок/решений в домашках (2026-03-29).
- [x] Кнопка «Написать в Telegram» — floating-кнопка + иконки в футере (2026-03-29).
- [ ] Иконки/бейджи для статуса разделов (пройден / в процессе / не начат) — пока декоративные, без бэкенда.
- [x] Яндекс.Метрика — счётчик 108294923, вебвизор, карта кликов (2026-03-29).

### 4.3. Явно НЕ делаем

- Разбивку основного README на отдельные страницы.
- Интерактивный трекинг прогресса менти.
- Систему авторизации / личный кабинет.
- Блог или раздел новостей (для этого есть Telegram-канал).
- SEO-оптимизацию и маркетинговые landing pages.

---

## 5. Ограничения

- **Бюджет: 0 ₽** (кроме домена, если решим подключить кастомный — `dementev.space` уже есть).
- **Время на поддержку: минимальное.** Рабочий процесс = «редактирую `.md` → push → сайт обновляется». Не должно быть отдельного шага сборки, ручного деплоя или npm-зависимостей, требующих обновления.
- **Стек автора: Python-first.** Решение на Python-тулинге предпочтительнее, чем на Node.js/Ruby (проще отлаживать при необходимости).
- **Один мейнтейнер.** Сайт поддерживает один человек — сложность решения должна быть соответствующей.

---

## 6. Итерации

### Спринт 1 — MVP: «Сайт, который просто работает» ✅ (2026-03-27)

**Scope:**

- Конфигурация генератора статического сайта.
- CI/CD pipeline (GitHub Actions → GitHub Pages).
- Главная страница = README.
- Подстраницы из `dwh-modeling/`.
- Фикс внутренних ссылок для dual compatibility.
- Адаптация Markdown для Python-Markdown (пустые строки перед списками, 4-пробельные отступы, заголовки `#`→`##`).

**Definition of Done:**

- ~~Сайт доступен по URL `https://dementev-dev.github.io/de-roadmap/`.~~ → `https://de.dementev.space/`
- Все ссылки внутри README работают и на сайте, и на GitHub.
- При пуше в `main` сайт автоматически пересобирается за < 2 минут (факт: ~34 сек).
- Контент на GitHub выглядит ровно так же, как до добавления сайта.

### Спринт 2 — «Удобство и навигация» (в процессе)

**Scope:**

- ~~Кастомный домен.~~ ✅ `de.dementev.space` (2026-03-27)
- ~~Тёмная тема.~~ ✅ из коробки Material (2026-03-27)
- ~~Сворачиваемые блоки.~~ ✅ `<details>` точечно в домашках (2026-03-29)
- ~~Кнопка «Написать ментору» (Telegram).~~ ✅ floating + футер (2026-03-29)
- ~~Базовая аналитика.~~ ✅ Яндекс.Метрика (2026-03-29)

### Спринт 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.