Документация для платформенной команды: что должно быть, чего не нужно

11 февраля 2026 г. 10K

Платформенная команда строит инфраструктуру, на которой работают другие команды. CI, deploy-пайплайны, общие библиотеки, kubernetes-кластеры, observability-стек. Документация платформы — это не «про продукт для пользователей», это руководство для разработчиков из других команд, которые подключаются к платформе.

Платформенная документация часто оказывается худшей в компании. Платформенная команда занята инфраструктурой, на доку времени нет, а внешним пользователям-разработчикам каждое подключение становится квестом «спроси в чате». Через год — десяток дублирующих систем, которые команды собрали сами, потому что платформа была непонятной. Разберу, что обязательно должно быть в документации платформы, и что часто пытаются положить лишнего.

Кто читатель

В отличие от документации публичного API, у платформенной — узкая аудитория: разработчики из других команд той же компании. Это меняет всё.

Они знают контекст — компанию, используемый стек, общие практики.
У них есть прямой канал связи с платформенной командой — Slack, тикеты, личные знакомства.
Они читают доку перед тем, как спросить в чате — но только если знают, что там есть ответ.
Они быстро забывают редко используемые детали — «как добавить новый сервис в кластер раз в полгода».

Из этого следует: документация платформы должна быть оптимизирована под «найти быстро» и «не забыть, как делать», а не под «учить с нуля».

Минимальный набор разделов

То, без чего платформенная документация бесполезна:

Onboarding для новой команды-пользователя.
How-to для типичных задач.
Reference платформы (что у нас есть).
Runbook-и для инцидентов.
SLA / SLO / контрактные обещания.
Контакты команды и каналы поддержки.

Этого хватает для самообслуживания. Дальше можно добавлять, но без этого — каждое подключение превращается в персональное сопровождение.

Onboarding для новой команды

«Новая команда хочет использовать платформу. Что делать?» Это первая страница, на которую попадает их team lead.

Что должно быть:

Шаги для регистрации команды (создание namespace, получение креденшалов, добавление в нужные группы).
Минимальный пример: hello-world сервис, развёрнутый через платформу.
Чеклист готовности к продакшену: что должно быть настроено перед тем, как уйти live.
Часто задаваемые вопросы первого месяца.

Onboarding должен быть проходимым самостоятельно. Если на каждом шаге команда упирается в «попросите у платформенной команды доступ» — это не onboarding, это очередь к окошку.

How-to: ключевая часть

Платформенная документация на 60% состоит из how-to. «Как развернуть Postgres-инстанс», «Как настроить CI для нового сервиса», «Как добавить алерт в Prometheus», «Как сделать canary-релиз».

Что важно в платформенных how-to:

Заголовок — конкретная задача. «Add a new microservice», не «Microservices on the platform».
Один сценарий. Один способ, проверенный, рекомендуемый. Альтернативы — в отдельных how-to, если они вообще нужны.
Готовый код-сниппет. Команда копирует, подставляет своё имя, работает.
Что делать, если не работает. Самые частые ошибки и решения внизу страницы.

Самый частый антипаттерн: how-to, в котором рассказывается «как это устроено внутри», прежде чем дать инструкцию. Команде из другого направления чаще всего не нужно знать внутренности — нужна работающая инструкция. Кто захочет глубже, прочитает explanation отдельно.

Reference: что у нас есть

Reference платформы — это каталог. «Какие сервисы предоставляет платформа», «Какие managed-сервисы доступны», «Какие шаблоны проектов есть», «Какие переменные окружения проставляются автоматически».

Структура зависит от платформы, но обычно включает:

Список managed-сервисов (Postgres, Redis, Kafka, и так далее) с версиями и параметрами.
Список шаблонов (стартовых проектов) для разных языков.
Конфиг платформенного манифеста (обычно YAML или подобное).
Список переменных окружения и секретов, доступных автоматически.
API внутренних сервисов платформы (если есть).

Reference должен быть машинно-сгенерирован из конфигов платформы, насколько возможно. Иначе — расходится с реальностью на каждом релизе.

Runbook-и для инцидентов

Когда что-то ломается, on-call команды-пользователя нужны конкретные действия, не философия. Runbook — это сценарий «вот случилось X, делайте Y».

# Runbook: Service is unreachable from outside

## Symptoms

- External requests get connection refused or timeout.
- Internal requests work fine.

## Most likely cause

Ingress configuration changed or broken.

## Steps

1. Check ingress status: `kubectl get ingress -n <your-ns>`
2. Look for events: `kubectl describe ingress <name> -n <your-ns>`
3. Verify DNS: `dig +short your-service.example.com`
4. If steps 1-3 are clean, escalate to platform team via #platform-oncall.

## Escalation

If unresolved in 15 minutes — page on-call via PagerDuty.

Runbook короткий, конкретный, с командами для копирования. Не «возможно, проблема в ingress». A конкретные шаги, в порядке вероятности.

Runbook-и хороших проектов покрывают 80% инцидентов, и команды-пользователи решают их сами без вовлечения платформенной команды в 3 ночи.

SLA, SLO, обещания платформы

Платформенная команда — это вендор для команд-пользователей. Им нужно знать, на что они могут рассчитывать.

# Platform SLA

## Availability

- Production tier: 99.9% per month (≈43 min downtime/month).
- Staging tier: 99% per month (best effort).
- Dev tier: best effort, no formal SLA.

## Response time

- P0 incidents: response within 15 min, 24/7.
- P1 incidents: response within 1 hour, business hours.
- P2 incidents: response within 1 business day.

## Maintenance windows

- Tuesday 06:00 UTC, weekly. Up to 30 min, no service interruption expected.
- Major upgrades announced 2 weeks ahead in #platform-announcements.

## Excluded events

- Issues caused by misconfigured user code.
- Issues with services explicitly marked "experimental".

Конкретные числа, понятные классы инцидентов, исключения. Без формулировок «постараемся быстро отреагировать».

Поддержка и эскалация

Где спросить, кому жаловаться, как эскалировать.

# Support

## Channels

- General questions: #platform-help (response by team during work hours).
- Documentation feedback: open PR or comment on the page.
- Production incidents: PagerDuty escalation, platform-oncall.

## Office hours

Tuesday 14:00–15:00 UTC. Open Zoom for direct questions.

## Escalation

If your team is blocked > 4 hours on a platform issue, escalate to:
- Platform team lead: <name>
- VP of Engineering: <name> (only after team lead unavailable)

Каждая команда-пользователь должна знать эти каналы наизусть. Печатают на стикерах в зум-комнатах команды.

Что не нужно класть в платформенную документацию

Маркетинговые тексты. «Наша платформа — современное решение для масштабируемых сервисов». Никто не читает, продавать не надо — пользователи внутренние.

Полную внутреннюю архитектуру. Команды-пользователи редко нуждаются в знании, как устроен ingress controller. Если нуждаются — отдельная страница «Architecture for the curious», на которую ссылаемся, но не на главной.

Декомпозицию сервисов платформы. «У нас есть 47 микросервисов, и вот их список». Не нужно никому, кроме самой платформенной команды.

Roadmap в общей доке. «В следующем квартале мы планируем X». Устаревает за месяц, путает команды-пользователей. Roadmap — отдельный документ для тех, кто специально его ищет.

Длинные tutorials в стиле «изучите Kubernetes». Платформенная команда не учит технологиям, она даёт абстракцию. Если нужно объяснять Kubernetes с нуля — это не платформенная документация, это onboarding для DevOps-инженеров.

Структура файлов

Что я обычно делаю:

platform-docs/
├── onboarding/
│   ├── new-team.md
│   ├── first-service.md
│   └── production-checklist.md
├── how-to/
│   ├── deploy/
│   ├── monitor/
│   ├── secure/
│   └── ...
├── reference/
│   ├── services/
│   ├── manifests/
│   └── env-vars.md
├── runbooks/
│   ├── service-unreachable.md
│   ├── high-error-rate.md
│   └── ...
├── platform-sla.md
└── support.md

Каждая папка — конкретный жанр. На главной — путеводитель по разделам. Поиск работает по всему сайту.

Где это живёт

Документация платформы — внутренний продукт, она почти всегда не публичная. Варианты хостинга:

Backstage TechDocs. Если есть Backstage, документация интегрируется в общий каталог. Удобно для крупных компаний.
MkDocs или Docusaurus на внутреннем поддомене. Markdown в репозитории, сборка в CI, хостинг на S3 или внутреннем nginx.
GitLab/GitHub Pages внутри организации. Если используется enterprise-версия.

Confluence-овые страницы для платформы — самый частый антипаттерн. Они быстро устаревают, с ними тяжело связать с кодом, обновляются от случая к случаю.

Метрики, что документация работает

Что мерить, чтобы понимать, работает ли документация:

Количество вопросов в support-чате на повторяющиеся темы. Должно сокращаться.
Время от первого подключения новой команды до первого сервиса в проде. Должно сокращаться.
Доля инцидентов, разрешённых без вовлечения платформенной команды. Должна расти.
Процент команд, которые провели polished onboarding (получили нужные доступы и развернули hello-world) самостоятельно.

Без этих метрик documenting feels like a black box: пишем-пишем, а понимаем ли мы, помогает ли это — непонятно.

Чек-лист готовности платформенной документации

Есть пошаговый onboarding, проходимый самостоятельно.
Есть how-to для топ-10 типичных задач.
Есть reference: список сервисов, шаблонов, манифестов.
Есть runbook-и для топ-10 типичных инцидентов.
Есть страница SLA с конкретными числами.
Есть страница с каналами поддержки и эскалации.
Документация хранится в репозитории, не в Confluence.
Поиск работает по всему сайту.
Reference сгенерирован из манифестов, не пишется руками.
Команда платформы регулярно (раз в квартал) смотрит на metrics и обновляет страницы под повторяющиеся вопросы.

Платформенная команда часто думает, что документация — это для тех, кто внешне «продаёт продукт». На самом деле — это инструмент масштабирования самой команды. Если команда из 5 человек обслуживает 20 команд-пользователей, документация — это разница между «отвечать на 100 вопросов в день» и «держать руку на пульсе и развивать платформу». Без документации платформенная команда становится узким местом организации; с документацией — мультипликатором.