Notion для разработки: playbook документации
Notion проходит невидимый порог отказа где-то в районе 300 страниц на инженерный воркспейс. До этой точки инструмент любят. После — поиск разваливается, накапливаются дубликаты, команда делится на два лагеря: тех, кто продолжает писать, и тех, кто перестал читать. Stack Overflow Developer Survey 2024 поставил Notion в топ-3 не-IDE инструментов у инженеров — и одновременно отметил его как #1 инструмент, от которого инженеры уходят в 18 месяцев, обычно именно из-за этого коллапса.
Коллапс — не вина Notion. Это проблема структуры. Вот playbook воркспейса из 7 баз, который остаётся навигируемым от 5 до 50 инженеров, и конкретные правила, которые предотвращают «проблему 300 страниц».
{/* truncate */}
Проблема: Notion заточен на писать, не на находить
Notion — лучший из протестированных нами инструментов, чтобы написать документ быстро. И один из худших, чтобы найти документ через три месяца. Эта разница и разъедает воркспейсы.
Инженерный воркспейс из 7 баз. У каждой базы один тип контента, один владелец, один lifecycle — структура, которая останавливает коллапс на 300 страниц.
Три failure mode, которые мы видели неоднократно:
- Суп из страниц. Каждый документ — страница в дереве. После 200 страниц найти что-либо без вопроса в Slack нельзя. Slack-to-doc ratio растёт. Писать перестают.
- Дубликаты runbook. Три инженера написали «как задеплоить staging» в трёх разных местах. Через полгода ни один не соответствует реальности. Новички получают рандомные версии.
- Протухшие ADR. Architecture Decision Records лежат рядом с эфемерными заметками встреч. Когда ADR смешаны с «черновик Q3 планирования», их авторитет размывается.
Фреймворк: 7 баз, у каждой одна задача
Используйте базы, а не вложенные страницы. База — это схема, фильтры, вью и, критически, один явный тип контента на строку.
База 1 — Team Home (landing страница команды)
Одна страница на команду. Запиннена сверху. Содержит:
- Состав команды (люди замечены правильно, чтобы показывались в сайдбарах)
- Ссылка на on-call
- Текущий sprint / cycle (обычно embed из Linear или Jira)
- Топ-5 runbook линкованы
- Последний postmortem линкован
Владелец: EM команды. Обновляется раз в две недели. Эту страницу новички букмаркают в первый день.
База 2 — Runbook DB
Одна строка на operational runbook. Схема:
| Свойство | Тип | Пример |
|---|---|---|
| Title | Title | «Rotate production Redis credentials» |
| Owner team | Relation | Platform |
| Last verified | Date | 2026-03-14 |
| Last verified by | Person | @Ahmed |
| Systems affected | Multi-select | Redis, API |
| Stale? | Formula | if (today - Last verified > 90) "⚠" else "" |
| Risk | Select | Low / Medium / High |
Формула Stale? — ключ. Любой runbook, не проверенный 90+ дней, получает видимый флаг. Раз в месяц владелец фильтрует «Stale = ⚠» и либо перепроверяет, либо архивирует.
База 3 — Architecture Decision Records (ADR)
Пронумерованные ADR-001, ADR-002. Схема:
| Свойство | Тип |
|---|---|
| Number | Number (auto-increment через button) |
| Title | Title |
| Status | Select (Proposed / Accepted / Superseded / Deprecated) |
| Context | Тело страницы |
| Decision | Тело страницы |
| Consequences | Тело страницы |
| Superseded by | Relation (self-referential) |
ADR никогда не удаляются. Superseded остаются читаемыми, чтобы «почему» текущих решений было прослеживаемым. Статья IEEE 2022 по architecture knowledge decay (Capilla et al.) показала: команды с постоянным ADR-логом имели в 2.4× меньше повторных решений по сравнению с теми, кто переписывал архитектурные документы на месте.
База 4 — Postmortems
Одна строка на инцидент. Схема:
| Свойство | Тип |
|---|---|
| Incident date | Date |
| Severity | Select (SEV-1 / SEV-2 / SEV-3) |
| Duration | Number (минуты) |
| Customer impact | Краткое описание |
| Root cause category | Multi-select (config, code, dependency, human, external) |
| Action items | Relation → action-items DB |
| Action items status | Rollup |
Магия — rollup колонка: одним взглядом видно, у каких postmortem остались открытые action items. Отчёт Google SRE 2024 отметил, что 43% action items из postmortem никогда не реализуются. Видимая статусная колонка делает этот failure mode невозможным для пряток.
База 5 — Onboarding Tasks
Шаблонируемая база, клонируется под каждого новичка. Задачи первой недели, первого месяца, первого квартала — как строки, с чекбоксами «Done?» и указателями владельцев. Новичок видит свой срез и идёт по нему в своём темпе.
База 6 — Team Docs (catch-all, но ограниченный)
Да, catch-all для «вот дизайн сервиса маршрутизации заказов» всё равно нужен. Но ограничьте его обязательными свойствами:
| Свойство | Обязательно |
|---|---|
| Title | Да |
| Owner | Да |
| Last updated | Да (авто) |
| Doc type | Да — Spec / Design / How-to / Reference / Research |
| Audience | Да — Internal / External / Both |
Без свойств — нет строки. Отсутствие required properties — основная причина гниения стандартных Notion-воркспейсов: страницы накапливаются без метаданных, фильтры становятся бесполезными.
База 7 — People (лёгкий справочник)
Одна страница на инженера. Местоимения, таймзона, текущие проекты, learning goals, on-call ротация. Не замена HRIS — дополнение. Используется EM для подготовки к 1:1 и для cross-team коллаборации.
Шаблоны, которые фиксируют структуру
Каждой базе нужны page templates, чтобы создание новой строки пред-заполняло правильную структуру. Пример:
Runbook template:
# {Title}
## Когда использовать
{условие триггера}
## Предварительно
- Доступ: {список}
- Инструменты: {список}
## Шаги
1. {шаг}
2. {шаг}
## Верификация
{как подтвердить успех}
## Откат
{шаги отмены}
## Связано
- Incident playbook: {link}
- ADR: {link}
Без шаблона инженеры пишут runbook в разных формах, и база деградирует до freeform-страниц.
Типичные ошибки
| Ошибка | Почему плохо | Как фиксить |
|---|---|---|
| Смесь баз и свободных страниц в одном дереве | Поиск выдаёт мусор | Строгий DB-only |
| Нет «stale» формулы на runbook | Устаревшие runbook вводят новичков в заблуждение | 90-дневный флаг |
| Разрешить удалять ADR | Потеря истории решений | ADR append-only; supersede, не delete |
| Глубокая вложенность (>3 уровней) | На глубину 4 никто не кликает | Плоские БД + хорошие фильтры |
| Шаринг отдельных страниц вне БД | Orphan-контент | Каждый документ живёт в базе |
| Полагаться только на Notion search | Notion search слаб на 500+ страницах | Multi-select Tags на БД |
| Нет retention-политики | Воркспейс растёт вечно | Ежеквартальный архив всего Last updated > 365d с тегом ephemeral |
Правила выживания на 300 страницах
Для команд, переходящих порог:
- Требуйте заполненности свойств в Team Docs. Блокируйте кнопку
Create, пока обязательные поля пусты. - Публикуйте месячный «stale hit list» — автоматом через фильтры Notion, отправка в канал EM.
- Архивируйте, не удаляйте. В Archive DB, не в корзину. Кому-то это понадобится через 2 года.
- Выделяйте под-воркспейсы для внешних документов. Всё публичное — в отдельном воркспейсе, шаримом наружу без риска.
- Подключайте Notion AI как last-resort search — хорош в семантическом вспоминании, но дорогой на масштабе ($8–10/user/месяц).
Как понять, что работает
Ежемесячно:
- Среднее время на поиск документа — спот-чек с новичками. Цель — меньше 3 минут.
- Доля протухших runbook — страницы с
Last verified > 90 дней. Цель < 15%. - Число дубликатов страниц — семантические дубли, ручной аудит. Цель — ноль активных.
- Slack-to-doc ratio — как часто спрашивают «где документ по X?» Снижение — хорошо.
PanDev Metrics напрямую в Notion не заглядывает, но видит отсутствие времени на поддержание документации. Если weekly IDE-активность команды показывает ноль времени в Markdown-редактировании или расширении Notion в браузере три недели подряд — это сигнал распада документации, вне зависимости от дашбордов Notion. Этот cross-tool-паттерн разобран в нашем knowledge-management посте, сравнивающем Notion, Confluence, GitHub Wiki и Git-native docs.
Честная оговорка: у нас нет данных, какие именно Notion-структуры коррелируют с долгосрочным успехом команды. Паттерн из 7 баз выше — проверен примерно на дюжине инженерных команд, с которыми мы работали, а не по cross-company исследованию.
Когда этот playbook не подходит
- Команды до 10 инженеров — большая часть этого — оверхед. Одной страницы + списка runbook хватит.
- Сильно регулируемые отрасли (fintech, medtech) — аудит часто вынуждает на Confluence или self-hosted wiki; compliance-сертификации Notion улучшаются, но отстают для финансовых и медицинских аудитов.
- Команды, уже вкладывающиеся в docs-as-code — не мигрируйте.
docs/+ MkDocs для чисто технического контента лучше, чем Notion когда-либо будет.