ddmitry/de-roadmap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
de-roadmap/project/PRD.md
T
ddadmin 4ad904efd0
Deploy MkDocs to VPS / deploy (push) Successful in 13s
Details
docs(site): дополнены инструкции восстановления публикации 
- Зачем:
  - runbook требовал незафиксированного контекста для первого деплоя и восстановления сайта на чистой VPS.
- Что:
  - добавлены prerequisites, установка пакетов, первый workflow, UFW и проверенный атомарный откат.
  - спецификация и PRD обновлены по факту завершённого переноса на VPS.
  - локальные команды Snap uv заменены на persistent Python venv.
- Проверка:
  - mkdocs build --strict выполнен через persistent venv пользователя gitea-runner.
  - последовательность rollback проверена на временном дереве releases и symlink.
2026-08-05 03:14:52 -04:00

14 KiB
Raw Permalink Blame History

PRD: Сайт для de-roadmap

Проектный документ. Техническая архитектура — в отдельном ADR.

1. Контекст и мотивация

Текущее состояние

Роадмап по Data Engineering живёт как Git-репозиторий. Основной origin размещён в собственной Gitea (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)

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

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

Навигация:

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

Деплой:

  • Автоматическая сборка и публикация при пуше в main.
  • Публикация без дополнительных расходов: собственная VPS как основной контур, GitHub Pages как резерв.

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

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

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

  • Кастомный домен: de.dementev.space (подключён 2026-03-27, переведён на VPS 2026-08-05).
  • Тёмная тема (переключатель light/dark).
  • Сворачиваемые блоки (<details>) — точечно, для подсказок/решений в домашках (2026-03-29).
  • Кнопка «Написать в Telegram» — floating-кнопка + иконки в футере (2026-03-29).
  • Иконки/бейджи для статуса разделов (пройден / в процессе / не начат) — пока декоративные, без бэкенда.
  • Яндекс.Метрика — счётчик 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 — миграция на другой генератор за день
Накладные расходы на поддержку растут Низкая Среднее Принцип «сайт опционален»: если мешает — удаляем конфиг, репо работает
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.
Reference in New Issue View Git Blame Copy Permalink