DOCS_MANAGEMENT_DECISION

Версия: 1.0.0
Дата: 2026-02-04
Статус: research/complete

1. ИНТЕРАКТИВНАЯ МАТРИЦА ВЫБОРА

Шаг 1: Определи размер команды

┌─────────────────────────────────────────────────────────┐
│                   РАЗМЕР КОМАНДЫ                        │
├─────────────────────────────────────────────────────────┤
│ □ 1-5 чел            → переходи на Шаг 2.1             │
│ □ 5-20 чел           → переходи на Шаг 2.2             │
│ □ 20-50 чел          → переходи на Шаг 2.3             │
│ □ 50-200 чел         → переходи на Шаг 2.4             │
│ □ 200+ чел           → переходи на Шаг 2.5             │
└─────────────────────────────────────────────────────────┘

Шаг 2.1: Малая команда (1-5 чел)

Вопросы:
□ Это техническая команда?
  ├─ ДА   → Docusaurus + ADR ⭐
  └─ НЕТ → Notion

□ Нужна версионирование?
  ├─ ДА   → Docusaurus / GitHub wiki ⭐
  └─ НЕТ → Notion

□ Есть GitHub репозиторий?
  ├─ ДА   → GitHub wiki (быстро и бесплатно) ⭐
  └─ НЕТ → Notion

РЕКОМЕНДАЦИЯ: Docusaurus + GitHub для техов, Notion для остальных
БЮДЖЕТ: $0 (если GitHub/Docusaurus) или $10-25/мес (Notion)

Шаг 2.2: Малая-средняя команда (5-20 чел)

Вопросы:
□ Состав команды?
  ├─ 100% tech     → GitHub wiki + Docusaurus ⭐
  ├─ 80% tech      → GitHub wiki (с Docusaurus для публики)
  ├─ 50/50         → GitHub wiki + Notion (KB)
  └─ <50% tech     → Notion

□ Есть продакт-менеджер?
  ├─ ДА   → Confluence (интеграция с Jira)
  └─ НЕТ  → Notion или GitHub wiki

□ Нужна интеграция с issues?
  ├─ ДА   → GitHub (Issues + wiki)
  └─ НЕТ  → Notion или Docusaurus

РЕКОМЕНДАЦИЯ: GitHub wiki + Docusaurus для документации, Notion для KB
БЮДЖЕТ: $0-50/мес

Шаг 2.3: Средняя команда (20-50 чел)

Вопросы:
□ Разделение на отделы?
  ├─ ДА   → Confluence (управление доступом по space)
  └─ НЕТ  → GitHub wiki или Notion

□ Нужны permissions?
  ├─ Да, fine-grained  → Confluence ⭐
  ├─ Базовые          → GitHub + Notion
  └─ Не нужны         → GitHub wiki

□ Интеграция с PM?
  ├─ ДА (есть Jira)   → Confluence + Jira ⭐
  ├─ ДА (GitHub)      → GitHub Issues + wiki
  └─ НЕТ              → Notion

РЕКОМЕНДАЦИЯ: Confluence + Jira (если есть PM), иначе GitHub wiki
БЮДЖЕТ: $120-600/мес (Confluence) или $0 (GitHub)

Шаг 2.4: Большая команда (50-200 чел)

Вопросы:
□ Есть требования compliance/audit?
  ├─ ДА   → Confluence Cloud Enterprise ⭐
  └─ НЕТ  → Confluence Cloud Standard

□ Количество пространств (teams)?
  ├─ <20  → GitHub + Docusaurus (с отдельными repos)
  ├─ 20-50  → Confluence
  └─ 50+  → Confluence Cloud Enterprise

□ Централизованная управление доступом?
  ├─ ДА   → Confluence (SAML, OAuth)
  └─ НЕТ  → GitHub + Notion

РЕКОМЕНДАЦИЯ: Confluence + Jira (стандартный выбор для большие команды)
БЮДЖЕТ: $600-2000/мес

Шаг 2.5: Очень большая организация (200+ чел)

Вопросы:
□ Требования к compliance/audit?
  ├─ ДА   → Confluence Data Center (on-premise) ⭐⭐
  └─ НЕТ  → Confluence Cloud Enterprise

□ Требования к масштабированию?
  ├─ Да (>5000 страниц)  → Confluence Data Center
  └─ Нет                  → Confluence Cloud

□ Собственный DataCenter?
  ├─ ДА   → Confluence Data Center (self-hosted)
  └─ НЕТ  → Confluence Cloud

РЕКОМЕНДАЦИЯ: Confluence Data Center или Confluence Cloud Enterprise
БЮДЖЕТ: $1500-10000+/мес (в зависимости от размера)

2. ТАБЛИЦА РЕШЕНИЙ: ЧТО ИСПОЛЬЗОВАТЬ ДЛЯ КАКОГО ТИПА ДОКУМЕНТОВ

┌──────────────────────────────────────────────────────────────────────┐
│ ТИП ДОКУМЕНТА → СИСТЕМА → ПРИЧИНА                                   │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│ 📋 README                                                            │
│ ├─ Если есть GitHub        → README.md в репо                       │
│ ├─ Если есть docs сайт     → Docusaurus intro                       │
│ └─ Если нет кода          → Notion Page                             │
│                                                                      │
│ 🏗️ АРХИТЕКТУРА                                                      │
│ ├─ Если это РЕШЕНИЕ       → ADR (обязательно!)                      │
│ ├─ Если нужна КРАСИВОСТЬ  → Docusaurus                              │
│ ├─ Если нужна ГИБКОСТЬ    → Confluence                              │
│ └─ Если это знание       → Notion                                   │
│                                                                      │
│ 🔌 API ДОКУМЕНТАЦИЯ                                                  │
│ ├─ Если auto-generated    → Swagger/OpenAPI (в docs сайте)          │
│ ├─ Если красивая нужна    → Docusaurus ⭐⭐⭐                      │
│ ├─ Если примеры нужны     → Docusaurus (MDX)                        │
│ └─ Если быстро            → Confluence                              │
│                                                                      │
│ 📖 GUIDES / TUTORIALS                                               │
│ ├─ Если на публику        → Docusaurus                              │
│ ├─ Если внутренние        → GitHub wiki                             │
│ └─ Если много структуры   → Notion Database                         │
│                                                                      │
│ 🎯 ПРОЦЕССЫ / HOW-TOs                                               │
│ ├─ Если часто меняются    → GitHub wiki                             │
│ ├─ Если стабильные        → Confluence                              │
│ └─ Если для non-tech      → Notion                                  │
│                                                                      │
│ ❓ FAQ / Knowledge Base                                              │
│ ├─ Если много Q&A        → Notion (Database + Relations) ⭐        │
│ ├─ Если простой поиск    → Confluence                              │
│ └─ Если интеграция с код  → GitHub wiki                            │
│                                                                      │
│ 🗣️ ОБСУЖДЕНИЯ / PROPOSALS                                           │
│ ├─ Если RFC              → GitHub Issues / Discussions             │
│ ├─ Если письма           → Confluence Comments                     │
│ └─ Если быстро           → Slack + потом документировать           │
│                                                                      │
│ ✅ РЕШЕНИЯ (DECISIONS)                                              │
│ ├─ Если это важно        → ADR (обязательно!) ⭐⭐                  │
│ ├─ Если просто заметка   → Confluence Page                         │
│ └─ Если обсуждение       → RFC → ADR                               │
│                                                                      │
│ 📊 СПЕЦИФИКАЦИИ                                                      │
│ ├─ Если техническая      → Confluence                              │
│ ├─ Если с таблицами      → Notion (Database)                       │
│ └─ Если с кодом          → Docusaurus (MDX)                        │
│                                                                      │
│ 📅 MEETING NOTES                                                     │
│ ├─ Если нужна история    → Confluence                              │
│ ├─ Если нужны действия   → Notion (Database) или Jira             │
│ └─ Если просто заметка   → GitHub wiki                             │
│                                                                      │
│ 🛣️ ROADMAP / TIMELINE                                              │
│ ├─ Если визуальная       → Notion (Timeline DB) ⭐⭐               │
│ ├─ Если с метриками      → Confluence (с macros)                   │
│ └─ Если в кодо           → Docusaurus (markdown table)             │
│                                                                      │
│ 🔄 CHANGELOG                                                         │
│ ├─ Если версионируется   → CHANGELOG.md в git ⭐                   │
│ ├─ Если красивое         → Docusaurus (blog)                       │
│ └─ Если постоянно        → Confluence                              │
│                                                                      │
│ 🚀 DEPLOYMENT / OPERATIONS                                          │
│ ├─ Если с кодом          → docs/ в git                             │
│ ├─ Если procedures       → GitHub wiki                             │
│ └─ Если runbooks         → Confluence                              │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

3. ЧЕКЛИСТ: ПРОВЕРКА КАЧЕСТВА ДОКУМЕНТАЦИИ

3.1 Структурированность

□ Есть ясная иерархия?
  □ На 1 уровень: категории
  □ На 2 уровень: подкатегории
  □ На 3 уровень: страницы
  □ Не более 5-6 уровней вложения

□ Есть оглавление (Table of Contents)?
  □ На главной странице
  □ На каждом разделе
  □ С ссылками (работают)

□ Есть навигация?
  □ Breadcrumbs (хлебные крошки)
  □ Backlinks (обратные ссылки)
  □ Next/Previous (логический порядок)

□ Есть индексация?
  □ Индекс документов
  □ Перекрёстные ссылки (cross-references)
  □ Тэги / категории

3.2 Актуальность

□ Дата последнего обновления указана?
  □ На каждом документе
  □ В metadata (frontmatter)

□ Версионирование?
  □ Version numbers (1.0, 2.0, ...)
  □ Changelog
  □ Архив старых версий

□ Obsolete документы помечены?
  □ DEPRECATED label
  □ Redirection на новую версию
  □ Дата когда будет удалено

□ Link check (ссылки работают)?
  □ Нет broken links
  □ Нет 404 ошибок
  □ Используются relative links (стабильные)

3.3 Полнота

□ Каждая страница содержит:
  □ Заголовок H1
  □ Краткое описание (1-2 абзаца)
  □ Основное содержимое
  □ Примеры (если применимо)
  □ Ссылки на related docs
  □ Last updated date

□ Каждый раздел содержит:
  □ Введение (что это)
  □ Why (почему это важно)
  □ How (как это использовать)
  □ Examples (примеры)
  □ Troubleshooting (если есть)

□ Архитектурные документы:
  □ Context (контекст)
  □ Decision (что выбрали)
  □ Consequences (последствия)
  □ Alternatives (что рассматривали)

3.4 Правильность

□ Техническая точность:
  □ Примеры кода работают
  □ URLs актуальны
  □ Commands выполняются
  □ API документация соответствует коду

□ Правописание:
  □ Нет опечаток
  □ Правильная грамматика
  □ Согласованная терминология

□ Форматирование:
  □ Consistent styling
  □ Правильный markdown
  □ Таблицы выглядят хорошо
  □ Code blocks правильно подсвечиваются

3.5 Поиск и открываемость

□ Поиск работает?
  □ Можно найти по ключевым словам
  □ Результаты релевантны
  □ SEO оптимизирована (если публичная)

□ Открытость для new members:
  □ Есть Getting Started guide
  □ Есть FAQ раздел
  □ Есть Glossary (словарь терминов)
  □ Есть ссылки на useful resources

□ Доступность:
  □ Страницы load быстро
  □ Mobile friendly
  □ Accessible for screen readers
  □ Dark mode (если есть)

3.6 Управление доступом

□ Permissions правильно установлены:
  □ Public docs - всем доступны
  □ Internal docs - только team
  □ Confidential docs - только те кто нужно
  □ Нет секретов в документации!

□ Версионирование:
  □ История сохраняется
  □ Можно откатиться на старую версию
  □ Видно кто и когда менял
  □ Comments на changes

□ Backup:
  □ Документация бэкапируется
  □ Есть disaster recovery план
  □ Можно восстановить из backup

4. ТАБЛИЦА: ИНСТРУМЕНТЫ ДЛЯ МИГРАЦИИ

Конвертеры документов

Проверка качества

5. ТАБЛИЦА: МИГРАЦИОННАЯ СТРАТЕГИЯ

План миграции (из Confluence в Docusaurus)

План миграции (из GitHub wiki в Notion)

6. ТАБЛИЦА: СРАВНЕНИЕ СТОИМОСТИ (на год)

Расчёт для команды из 20 чел

Из → В	Инструмент	Команда	Качество
Confluence → Markdown	pandoc	`pandoc -f docx -t markdown`	⭐⭐⭐
HTML → Markdown	pandoc	`pandoc -f html -t markdown`	⭐⭐⭐
Notion → CSV	Notion API	`notion2md`	⭐⭐⭐
Google Docs → Markdown	pandoc	Export as DOCX → markdown	⭐⭐
PDF → Markdown	pdf2md	`pdftotext`	⭐⭐
Markdown → HTML	pandoc	`pandoc -f markdown -t html`	⭐⭐⭐⭐
Markdown → PDF	pandoc	`pandoc -o file.pdf file.md`	⭐⭐⭐

Инструмент	Для	Команда
linkcheck	Broken links	`markdown-link-check file.md`
markdownlint	Markdown quality	`markdownlint file.md`
spellcheck	Орфография	`aspell check file.md`
yamllint	YAML syntax	`yamllint file.yaml`
validate-docs	Структура	Custom script

Шаг	Что делаем	Время	Инструменты
1	Экспорт Confluence (XML)	30 мин	Confluence Export
2	Разархивирование	10 мин	unzip
3	Конвертирование XML → HTML	30 мин	pandoc
4	Конвертирование HTML → Markdown	30 мин	pandoc
5	Фиксирование ссылок	1-2 часа	grep + sed / python
6	Фиксирование таблиц	1-2 часа	manual
7	Фиксирование изображений	1 час	manual copy
8	Setup Docusaurus	30 мин	npm create docusaurus
9	Import markdown	10 мин	cp -r
10	Test & QA	1-2 часа	local build + review
11	Deploy	30 мин	npm run deploy

Шаг	Что делаем	Время	Инструменты
1	Clone wiki	5 мин	`git clone wiki.git`
2	Экспорт markdown → Notion	30 мин	notion-md или API
3	Импорт в Notion	15 мин	Notion Import
4	Фиксирование структуры	1 час	manual
5	Добавление relations	30 мин	Notion UI
6	Миграция images	30 мин	batch upload
7	Test & QA	1 час	review

┌────────────────────────────────────────────────────────────────────┐
│ СИСТЕМА              │ МЕСЯЧНАЯ      │ ГОДОВАЯ (20 чел)            │
├────────────────────────────────────────────────────────────────────┤
│ GitHub wiki          │ $0            │ $0                          │
│ Docusaurus (S3)      │ ~$10 (S3)     │ ~$120                       │
│ GitLab wiki          │ $0            │ $0 (если на своем server)   │
│ Notion               │ $10-25/чел    │ $200-600/мес ($2400-7200)   │
│ Confluence Cloud     │ $6/чел        │ ~$1440/год (20 × $6)        │
│ Confluence + Jira    │ $6-12/чел     │ ~$1440-3360/год             │
│ VitePress (S3)       │ ~$10 (S3)     │ ~$120                       │
│ ReadTheDocs          │ $0 (или $10)  │ $0-120                      │
└────────────────────────────────────────────────────────────────────┘

Бюджет рейтинг (от дешево к дорого):
1. GitHub wiki / GitLab wiki - $0
2. Docusaurus / ReadTheDocs - $100-200/год
3. Confluence Cloud - ~$1500/год
4. Notion - ~$2500-7000/год
5. Confluence + Jira - ~$3000-5000/год

7. ТАБЛИЦА: ИНТЕГРАЦИИ

Что можно интегрировать

Система	GitHub	GitLab	Slack	Jira	Linear	Notion
Confluence	⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	—	—
GitHub wiki	⭐⭐⭐⭐	—	⭐⭐	—	⭐⭐	⭐⭐
GitLab wiki	—	⭐⭐⭐⭐	⭐⭐	⭐	⭐	⭐⭐
Notion	⭐	⭐	⭐⭐	⭐⭐	⭐⭐	⭐⭐⭐⭐
Docusaurus	⭐⭐⭐	⭐⭐⭐	—	—	—	—

Популярные интеграции:
- Confluence ← → Jira (встроено)
- GitHub / GitLab ← → Slack (notifications)
- Notion ← → Slack (mentions)
- Docusaurus ← GitHub (deploy on push)

8. ТАБЛИЦА: BEST PRACTICES ПО СИСТЕМЕ

Confluence + Jira

✅ DO:
□ Создавать Space per team (не per project)
□ Использовать Labels для categorization
□ Linking Issues to Confluence pages
□ Version control встроен
□ Regular backups

❌ DON'T:
□ Не создавать 100+ spaces (управление)
□ Не смешивать несвязанные docs в один space
□ Не использовать глубокую вложенность (>5 уровней)
□ Не забывать обновлять docs
□ Не хранить secrets в Confluence

GitHub / GitLab wiki

✅ DO:
□ Использовать wiki для процессы и HOW-TOs
□ Использовать docs/ для версионируемую документацию
□ Писать README.md в root репо
□ Использовать Issues для обсуждения
□ Linking wiki to Issues

❌ DON'T:
□ Не хранить большие binaries в git
□ Не забывать про .gitignore
□ Не создавать>10 уровней вложения
□ Не использовать wiki для быстрыхъ заметок (используй Issues)
□ Не забывать обновлять docs с кодом

Notion

✅ DO:
□ Использовать Database для структурированных данных
□ Использовать Relations для связей между базами
□ Использовать Rollups для aggrerations
□ Использовать Templates для повторяющихся записей
□ Использовать Filters and Sorts для views

❌ DON'T:
□ Не смешивать >10 типов данных в одной базе
□ Не создавать слишком сложные формулы
□ Не забывать про backup (Notion не отменяет deleted)
□ Не использовать для version control кода
□ Не жалеть на permissions (всё может быть видно)

Docusaurus / VitePress

✅ DO:
□ Использовать Markdown для всех docs
□ Версионировать documentation (versioned_docs/)
□ Использовать MDX для интерактивных примеров
□ Автоматизировать deployment (CI/CD)
□ Регулярно обновлять dependencies

❌ DON'T:
□ Не создавать слишком глубокую вложенность
□ Не забывать про SEO (metadata)
□ Не игнорировать broken links
□ Не хранить большие binaries (используй CDN)
□ Не забывать про analytics (отследи что ищут)

ADR / RFC

✅ DO:
□ Писать ADR для важных решений
□ Использовать RFC для обсуждения
□ Версионировать ADRs (0001, 0002, ...)
□ Связывать с кодом (pull requests)
□ Обновлять статус (Accepted → Deprecated)

❌ DON'T:
□ Не писать ADR для тривиальных решений
□ Не забывать про context
□ Не пропускать alternatives
□ Не мешать RFC (обсуждение) и ADR (решение)
□ Не игнорировать старые ADRs (mark as Superseded)

9. БЫСТРАЯ ДИАГНОСТИКА: ЧТО ВЫБРАТЬ

Ответь на вопросы ДА или НЕТ:

1. У вас есть GitHub репозиторий?
   ДА → Go to Q3
   НЕТ → Go to Q2

2. Команда 100% техническая?
   ДА → Docusaurus + ADR
   НЕТ → Notion

3. Нужна версионирование кода + docs вместе?
   ДА → Docusaurus (docs/ в репо) или GitHub wiki
   НЕТ → Go to Q4

4. Нужны структурированные данные (CRM, Inventory)?
   ДА → Notion (использовать Database)
   НЕТ → Go to Q5

5. Есть Project Manager?
   ДА → Confluence + Jira
   НЕТ → GitHub wiki

6. Бюджет ограничен?
   ДА → GitHub wiki (free)
   НЕТ → Confluence ($6/чел)

7. Нужны архитектурные решения?
   ДА → ADR обязательно (в git)
   НЕТ → Confluence или Notion

10. РЕЗУЛЬТАТ МАТРИЦЫ

Используй этот выход для финального выбора:

┌──────────────────────────────────────────────────────────┐
│ РЕЗУЛЬТАТЫ АНАЛИЗА                                       │
├──────────────────────────────────────────────────────────┤
│                                                          │
│ Рекомендация #1: [Система]                             │
│ Оценка соответствия: [90%]                             │
│ Бюджет: [$XXX/год]                                     │
│ Подходит для: [типы документов]                        │
│                                                          │
│ Рекомендация #2: [Система]                             │
│ Оценка соответствия: [70%]                             │
│ Бюджет: [$XXX/год]                                     │
│ Подходит для: [типы документов]                        │
│                                                          │
│ Рекомендация #3: [Система]                             │
│ Оценка соответствия: [50%]                             │
│ Бюджет: [$XXX/год]                                     │
│ Подходит для: [типы документов]                        │
│                                                          │
└──────────────────────────────────────────────────────────┘

ПРИМЕЧАНИЕ: Обычно лучший вариант - комбинация 2-3 систем:
- GitHub wiki + Docusaurus (для docs сайта)
- Notion (для Knowledge Base)
- ADR в git (для architectural decisions)

Матрицы и чеклисты для выбора системы документации