Перейти к основному содержимому

Documentation Scope

Что должно жить на сайте​

  • продуктовый обзор и user flows;
  • экранные описания с состояниями, навигацией, данными и запросами;
  • developer setup, локальная конфигурация и CI/CD;
  • архитектурные разделы по auth, networking, ranking, statistics и analytics;
  • operational reference: troubleshooting, update delivery, backend integration points.

Что не стоит тащить в сайт как отдельные страницы​

  • временные заметки уровня TODO;
  • дубли одного и того же flow в нескольких разделах;
  • микродоки про единичные alert-окна без отдельной логики;
  • пиксельные значения, если они не являются контрактом дизайна;
  • подробное описание каждого helper-метода или локальной UI-функции.

Практическое правило​

Сайт документирует поведение, контракты и архитектуру.
Детали низкого уровня остаются в коде, именах типов, тестах и коротких inline-комментариях.

Как принимать решение​

Добавляйте материал на сайт, если выполняется хотя бы одно из условий:

  • это нужно новому разработчику для старта без чтения половины репозитория;
  • это объясняет внешний контракт клиента с backend или платформой;
  • это влияет на пользовательское поведение экрана;
  • это помогает безопасно выпускать, дебажить или сопровождать приложение.

Не добавляйте материал на сайт, если он устареет после одного локального рефакторинга и не несет ценности вне конкретного файла.