Организация базы знаний команды в Confluence

Базу знаний стоит строить так, чтобы любой участник команды мог быстро найти актуальные договорённости, документацию по продукту и технические материалы. Основной принцип: одна тема — одна страница с понятным владельцем, датой последней проверки и ссылками на связанные материалы.

Общая структура пространства

  • Главная страница — навигация по разделам, контакты владельцев направлений, ссылки на ключевые документы и последние обновления.
  • Product / Общие материалы — описание продукта, доменная модель, глоссарий, roadmap, требования и решения, общие для всех команд.
  • Architecture — архитектурные схемы, интеграции, ADR (Architecture Decision Records), нефункциональные требования.
  • FE — документация фронтенд-разработки.
  • BE — документация бэкенд-разработки.
  • Analytics — документация аналитиков, метрики, события и отчёты.
  • Processes — процессы разработки, релизы, инциденты, onboarding, шаблоны встреч.
  • Archive — устаревшие документы, которые нельзя удалять, но не следует использовать как актуальные.

Единые правила для всех разделов

  • Использовать единый шаблон страницы: цель, статус, владелец, дата обновления, содержание, ссылки на связанные документы.
  • Указывать статус документа: Draft, Active, Deprecated, Archived.
  • Назначать владельца каждой страницы или подраздела.
  • Пересматривать критичные документы минимум раз в квартал.
  • Не хранить длинные обсуждения в Confluence: решения фиксировать кратко, а ссылку на обсуждение оставлять внизу страницы.
  • Для важных технических решений создавать отдельные ADR с контекстом, вариантами, решением и последствиями.
  • Использовать единые метки: frontend, backend, analytics, architecture, api, events, onboarding, runbook, adr.

Раздел FE

Раздел фронтенда должен содержать всё, что нужно разработчику для запуска проекта, понимания архитектуры интерфейса и соблюдения инженерных договорённостей.
  • Getting Started
  • окружение и локальный запуск;
  • доступы и переменные окружения;
  • команды для сборки, тестов и линтинга;
  • FAQ по типовым проблемам.
  • Архитектура FE
  • структура репозитория;
  • слои приложения и правила зависимостей;
  • управление состоянием;
  • маршрутизация;
  • работа с API и обработка ошибок.
  • UI и Design System
  • ссылки на дизайн-макеты;
  • библиотека компонентов;
  • правила использования компонентов;
  • accessibility и адаптивность;
  • соглашения по стилям и темам.
  • Кодовые стандарты
  • TypeScript/JavaScript conventions;
  • правила именования;
  • linting, formatting, code review;
  • тестирование компонентов и e2e.
  • Интеграции
  • контракты API;
  • авторизация;
  • feature flags;
  • аналитические события;
  • внешние SDK.
  • Release и эксплуатация
  • процесс релиза;
  • окружения;
  • мониторинг ошибок;
  • rollback-инструкции.

Раздел BE

Раздел бэкенда должен описывать сервисы, их ответственность, контракты, данные и операционные процедуры.
  • Getting Started
  • запуск сервисов локально;
  • зависимости и инфраструктура;
  • доступы;
  • миграции;
  • тестовые данные.
  • Сервисы и домены
  • каталог сервисов;
  • назначение каждого сервиса;
  • владельцы;
  • зависимости;
  • ссылки на репозитории и дашборды.
  • API
  • REST/gRPC/GraphQL-контракты;
  • версионирование;
  • ошибки и коды ответов;
  • авторизация и права доступа;
  • примеры запросов и ответов.
  • Данные
  • схемы БД;
  • описание ключевых сущностей;
  • миграции;
  • политики хранения и удаления данных;
  • кеширование и очереди.
  • Архитектура и интеграции
  • контекстные и контейнерные схемы;
  • внешние системы;
  • очереди, события и обработчики;
  • retry, idempotency, DLQ;
  • ADR.
  • Эксплуатация
  • мониторинг и алерты;
  • логи и трассировка;
  • runbook для инцидентов;
  • масштабирование;
  • резервное копирование и восстановление.
  • Безопасность
  • секреты и доступы;
  • PII/персональные данные;
  • threat model;
  • требования к аудиту.

Раздел Analytics

Раздел аналитики должен быть единым источником правды для определения метрик, событий, витрин и правил интерпретации данных.
  • Глоссарий
  • бизнес-термины;
  • сущности;
  • статусы;
  • единые определения пользователей, заказов, конверсий и других ключевых понятий.
  • Метрики
  • каталог метрик;
  • формула расчёта;
  • источник данных;
  • владелец;
  • периодичность обновления;
  • ограничения интерпретации.
  • Событийная аналитика
  • схема событий;
  • обязательные параметры;
  • правила именования;
  • примеры payload;
  • статус внедрения событий на FE и BE.
  • Источники данных
  • описание систем-источников;
  • таблицы и витрины;
  • data lineage;
  • задержки загрузки и SLA.
  • Отчёты и дашборды
  • каталог дашбордов;
  • назначение;
  • ссылки;
  • владельцы;
  • описание фильтров и ключевых показателей.
  • Эксперименты
  • процесс A/B-тестов;
  • гипотезы;
  • дизайн эксперимента;
  • критерии успеха;
  • результаты и принятые решения.
  • Качество данных
  • проверки;
  • известные ограничения;
  • инциденты данных;
  • правила исправления исторических данных.

Связи между FE, BE и Analytics

Для кросс-функциональных задач полезно создать общий раздел Tracking & Contracts, в котором фиксируются договорённости между направлениями.
  • Таблица событий: название события, триггер, параметры, источник, владелец FE/BE, потребитель в аналитике, статус реализации.
  • Каталог API-контрактов: endpoint или event, версия, владелец BE, потребитель FE, ссылка на спецификацию.
  • Изменения данных: описание изменения, затронутые сервисы, таблицы, дашборды, дата внедрения и план миграции.
  • Чек-лист запуска фичи: UI, API, события, метрики успеха, мониторинг, документация, rollback.

Рекомендуемые шаблоны страниц

Шаблон технической страницы

Статус: Active Владелец: команда / сотрудник Последняя проверка: дата Связанные материалы: ссылки

Цель

Кратко описать назначение документа.

Основная информация

Описание решения, процесса или компонента.

Ограничения и риски

Что важно учитывать при использовании.

Ссылки

Репозитории, задачи, дашборды, ADR, API-спецификации.

Шаблон ADR

Название: краткое описание решения Статус: Proposed / Accepted / Superseded Дата: дата Владелец: команда или автор

Контекст

Какую проблему нужно решить.

Рассмотренные варианты

Перечень вариантов с плюсами и минусами.

Решение

Выбранный вариант и причина выбора.

Последствия

Технические, продуктовые и операционные последствия.

Поддержание актуальности

  • Назначить владельцев разделов FE, BE и Analytics.
  • Добавить на главную страницу список документов, требующих пересмотра.
  • Использовать напоминание о ревью раз в квартал для страниц со статусом Active.
  • Устаревшие материалы переводить в Deprecated с явной ссылкой на актуальную замену.
  • Во время завершения крупных задач включать обновление Confluence в Definition of Done.
  • На onboarding новых сотрудников собирать обратную связь: какие страницы помогли, а каких не хватает.