# PRD: Сайт для de-roadmap > Проектный документ. Техническая архитектура — в отдельном ADR. --- ## 1. Контекст и мотивация ### Текущее состояние Роадмап по Data Engineering живёт как Git-репозиторий. Основной origin размещён в собственной Gitea ([ddmitry/de-roadmap](https://git.dementev.space/ddmitry/de-roadmap)), а GitHub Pages сохраняется как резерв после восстановления доступа к GitHub: - Основной контент — монолитный `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] Публикация без дополнительных расходов: собственная VPS как основной контур, GitHub Pages как резерв. **Совместимость с репо:** - [x] Все `.md` файлы остаются читаемыми на GitHub «как есть». - [x] `README.md` в корне репо продолжает рендериться на главной странице репозитория. - [x] Добавление сайта не ломает существующую структуру — если удалить конфиг сайта, репо работает как раньше. ### 4.2. Желательные (Спринт 2+) - [x] Кастомный домен: `de.dementev.space` (подключён 2026-03-27, переведён на VPS 2026-08-05). - [x] Тёмная тема (переключатель light/dark). - [x] Сворачиваемые блоки (`
`) — точечно, для подсказок/решений в домашках (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) - ~~Сворачиваемые блоки.~~ ✅ `
` точечно в домашках (2026-03-29) - ~~Кнопка «Написать ментору» (Telegram).~~ ✅ floating + футер (2026-03-29) - ~~Базовая аналитика.~~ ✅ Яндекс.Метрика (2026-03-29) ### Спринт 3 — «Контент и визуал» (по необходимости) **Scope:** - Визуальная карта роадмапа (интерактивная диаграмма прохождения). - Страница «О менторе» / «Отзывы выпускников» (когда будут выпускники). - Расширение контента: новые разделы роадмапа → автоматически появляются на сайте. --- ## 7. Риски | Риск | Вероятность | Влияние | Митигация | |------|-------------|---------|-----------| | Ссылки ломаются при конвертации (GitHub vs сайт) | Средняя | Высокое | Стратегия dual-compatible links в ADR; автотест ссылок в CI | | Кириллические якоря рендерятся по-разному | Средняя | Среднее | Тестирование конкретного генератора; при необходимости — латинские id | | Генератор сайта перестаёт поддерживаться | Низкая | Среднее | Контент в plain Markdown — миграция на другой генератор за день | | Накладные расходы на поддержку растут | Низкая | Среднее | Принцип «сайт опционален»: если мешает — удаляем конфиг, репо работает | | VPS временно недоступна | Низкая | Высокое | Опубликованный сайт не зависит от Gitea; GitHub Pages сохраняется как ручной резерв | --- ## 8. Открытые вопросы 1. **Домен.** Использовать GitHub Pages URL или сразу подключить кастомный домен? Можно решить в Спринте 2. 2. **README.md в корне vs docs/.** Оставляем README.md в корне (GitHub его рендерит) и используем его же как `index.md` для сайта, или делаем симлинк / копию? → Решение в ADR. 3. **Структура `docs/` директории.** Нужно ли вообще создавать `docs/`, или генератор может работать прямо с корнем репо? → Решение в ADR.