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