Сравнительный анализ практик управления документацией в IT проектах

Atlassian Cloud
├── Jira (управление задачами)
│   ├── Issues (проблемы)
│   ├── Epics (функциональность)
│   └── Sprints (итерации)
│
└── Confluence (документация)
    ├── Spaces (команды/проекты)
    │   ├── Pages (документы)
    │   └── Child Pages (∞ вложение)
    ├── Permissions (доступ по группам)
    └── Version Control (история)

Source of Truth (SSOT):
  Jira: состояние задач, спринты, метрики
  Confluence: контекст, причины, анализ

Как организуют:
  1. Space = Team или Project
  2. Parent Page = тема (e.g. "Architecture")
  3. Child Pages = детали (e.g. "API", "Database")
  4. Permissions по Space (не по Page)
  5. Макросы для встраивания данных из Jira

SSOT правило:
- Jira Issue = одна команда, один размер
- Confluence spec = общая информация
- Макрос Jira → Confluence = синхронизация

Хлебные крошки (автоматические):
  Site > Space > Parent Page > Child Page

Поиск:
  - Full-text по всей Space
  - Фильтры по Page Type
  - Labels для группировки

Макросы для связей:
  {include:/другая-страница}
  {jira-issues:query=project=ABC}

GitHub/GitLab
├── Repository (код)
│   ├── .github/
│   │   ├── ISSUE_TEMPLATE/
│   │   ├── PULL_REQUEST_TEMPLATE/
│   │   └── README.md (профиль организации)
│   │
│   ├── docs/ (опционально)
│   │   ├── architecture/
│   │   ├── api/
│   │   └── deployment/
│   │
│   └── wiki/ (встроенное хранилище Git)
│       ├── Home.md
│       ├── API.md
│       └── Guides/
│           └── Getting-Started.md
│
└── Issues & Projects (задачи)
    ├── Issues (обсуждение)
    ├── Pull Requests (код + review)
    └── Projects (визуальная доска)

Стратегия хранения:
  1. docs/ в репо = версионируется с кодом
  2. wiki/ отдельный Git = гибкость, не в истории кода
  3. Issues = обсуждение + ссылки на docs
  4. Projects = визуализация workflow

Рекомендуемое разделение:
  Code-related docs (CHANGELOG, API):
    → docs/ с кодом (в истории)

  Knowledge base:
    → wiki/ отдельный Git (гибкий)

  ADRs:
    → docs/decisions/ или wiki/ (оба варианта)

  Процессы:
    → wiki/ (не меняется с кодом)

Как избежать:
1. SINGLE REPO for all docs
2. README.md = точка входа
3. wiki/ = гибкая структура
4. docs/ = неменяемые (с версионированием кода)
5. Ссылки: относительные (устойчивы к рефакторингу)

Пример навигации:
README.md → wiki/Getting-Started.md
         → docs/API.md (версионируется)
         → Issues/Discussions

Гиперссылки:
  [Link](../docs/api.md)        ← относительная
  [Link](/docs/api.md)          ← абсолютная в репо
  [Link](../wiki/Home.md)       ← в wiki

Sidebar для docs/:
  docusaurus.config.js
  или .github/sidebar.json

Поиск:
  GitHub search (всё)
  wiki поиск
  grep + код (локально)

Notion Workspace
├── Database 1 (container for multiple data sources)
│   ├── Data Source: Products
│   │   ├── Properties: Name, Price, Category
│   │   └── Relations → Category Database
│   └── Data Source: Inventory
│       ├── Properties: SKU, Stock
│       └── Rollups → Products
│
├── Database 2 (Projects)
│   ├── Data Source: Tasks
│   └── Data Source: Resources
│
└── Pages (Wiki)
    ├── Getting Started
    └── Nested Pages (∞)
        ├── Architecture
        └── Guide
            └── Advanced

Подход Notion:
1. Pages = структурные (иерархия)
2. Databases = данные (relations)
3. Properties = метаданные (типы)
4. Relations = связи между данными
5. Rollups = агрегация

Типовая структура:
  Documentation (Space)
  ├── Getting Started (Page)
  ├── API (Database with related calls)
  ├── Team (Database with relations)
  ├── Architecture
  │   ├── Overview (Page)
  │   └── Components (Database)
  └── Knowledge Base (Database)
      ├── Category (relation)
      └── Tags (multi-select)

Избежание дублирования:
1. Relations = двусторонние ссылки
2. Rollups = вычисляемые поля (не копируют данные)
3. Database + Links = SSOT

Пример:
  Database "Projects"
    ├── Status: "Active"
    └── Owner (relation → People database)

  Если обновить Person в People database
  → автоматически синхронизируется в Projects

Структуры навигации:

1. Sidebar (левая панель)
   - Закреплённые страницы
   - Favorites (избранное)
   - Recently viewed

2. Breadcrumbs (хлебные крошки)
   - Workspace > Database > Page

3. Relations (ссылки между базами)
   - Видны в контексте записи

4. Поиск
   - Full-text + filters
   - Быстрый по названиям

Docusaurus Project
├── docs/
│   ├── intro.md
│   ├── api/
│   │   ├── overview.md
│   │   └── endpoints.md
│   ├── guides/
│   │   └── getting-started.md
│   └── versioned_docs/       ← история версий
│       ├── v1.0/
│       └── v2.0/
│
├── static/
│   └── images/
│
├── docusaurus.config.js      ← конфиг
├── sidebars.js               ← навигация
└── package.json

Build → Static HTML site

Структура документации:
  docs/                    ← основные docs
  ├── intro.md            ← главная
  ├── fundamentals/       ← основы
  ├── advanced/           ← продвинутое
  └── api-reference/      ← справочник

Versioning:
  docs/                   ← текущая версия
  versioned_docs/v1.0/   ← архивные версии
  versioned_docs/v2.0/

Blog (если нужен):
  blog/
  ├── 2024-01-01.md
  └── 2024-01-15.md

Конфигурация:
  docusaurus.config.js    ← основной конфиг
  sidebars.js             ← структура навигации

Стратегия:
1. DRY = один источник (markdown файл)
2. Imports = переиспользование (MDX)
3. Version control = одна версия в docs/
4. Versioning tool = автоматический архив

Пример DRY:
  // guides/setup.md
  import CodeBlock from '@theme/CodeBlock';
  import Setup from '!!raw-loader!../snippets/setup.js';

  <CodeBlock language="js">{Setup}</CodeBlock>

  → автоматически синхронизируется с кодом

Sidebar (sidebars.js):
  {
    tutorialSidebar: [
      'intro',
      {
        label: 'Guides',
        items: ['guides/setup', 'guides/deploy']
      },
      {
        label: 'API',
        items: ['api/overview', 'api/endpoints']
      }
    ]
  }

Хлебные крошки:
  Documentation > Guides > Getting Started

Поиск:
  Встроенная Algolia интеграция
  или локальный Lunr

Версионирование:
  Website > версия selector > v1.0 docs

Решения / Обсуждения
├── RFC (Request for Comments)
│   ├── Предложение решения
│   ├── Открыто для обсуждения
│   └── Status: Proposed → Accepted/Rejected
│
└── ADR (Architecture Decision Record)
    ├── Окончательное решение
    ├── История + контекст
    └── Status: Proposed → Accepted → Deprecated

Структура:
├── docs/decisions/        или
├── adr/                   или
└── rfcs/
    ├── 0001-auth-strategy.md
    ├── 0002-database-choice.md
    └── 0003-microservices.md

# ADR 0001: Choose Database Technology

**Date:** 2024-01-15
**Status:** Accepted

## Context
We need a database that...

## Decision
We will use PostgreSQL because...

## Consequences
- Positive: ACID compliance, reliability
- Negative: No horizontal scaling

## Alternatives Considered
1. MongoDB - flexible schema but...
2. DynamoDB - managed but vendor lock-in...

# RFC: Implement Microservices Architecture

**Date:** 2024-01-15
**Status:** Proposed

## Motivation
Current monolith causes...

## Proposal
Split into microservices:
- User Service
- Order Service
- Payment Service

## Questions for Discussion
1. How to handle transactions?
2. What about deployment?

## Drawbacks
- Complexity increases
- Network latency

Please provide feedback by: 2024-01-25

ADR vs RFC:
  RFC:
    - Открытое предложение
    - Для обсуждения и сбора feedback
    - Status: Proposed/Discussion
    - Когда: до принятия решения

  ADR:
    - Финальное решение
    - Записанный выбор + причины
    - Status: Accepted/Deprecated
    - Когда: после принятия решения

Последовательность:
  1. Обнаружена проблема
  2. RFC предложено несколько решений
  3. Team обсуждает (комментарии)
  4. Выбирается лучшее
  5. Пишется ADR с финальным решением

Избежание:
1. ADR = одна запись (не меняется)
2. Если решение меняется → новый ADR
3. Старый ADR помечается как "Superseded"

Пример:
  ADR-0001: Use MongoDB
    Status: Superseded (by ADR-0003)

  ADR-0003: Use PostgreSQL
    Status: Accepted
    Supersedes: ADR-0001

Структура индекса:
  docs/decisions/
  ├── README.md (индекс)
  │   - Links on all ADRs
  │   - Status filtering
  ├── 0001-auth-strategy.md
  ├── 0002-database-choice.md
  └── 0003-microservices.md

README.md (индекс):
  # Architecture Decisions

  | # | Title | Status | Date |
  |----|-------|--------|------|
  | 1 | Auth Strategy | Accepted | 2024-01 |
  | 2 | Database | Accepted | 2024-01 |
  | 3 | Microservices | Superseded | 2024-02 |

README для проекта:
  → GitHub README.md (если код)
  → Docusaurus intro (если docs сайт)

Техническая архитектура:
  → ADR + Docusaurus (версионировано)
  → Confluence (если обсуждение)

API документация:
  → Docusaurus (красивая, searchable)
  → Swagger/OpenAPI (если auto-generated)

Knowledge base:
  → Notion (flexible, searchable)
  → Confluence (с поиском)

Процессы:
  → Wiki (GitLab/GitHub)
  → Notion (если non-tech)

Решения/выводы:
  → ADR (если архитектурные)
  → RFC (если на обсуждение)
  → Confluence Page (если одноразовое)

Task tracking:
  → Jira (с Confluence интеграцией)
  → GitHub Issues (если в одном месте с кодом)
  → Notion Database (если лёгкая система)

Структура:
repo/
├── README.md
├── .github/
│   └── ISSUE_TEMPLATE/
├── docs/
│   ├── architecture/
│   ├── api/
│   └── deployment/
├── decisions/
│   ├── 0001-auth.md
│   └── 0002-database.md
└── wiki/ (GitLab wiki or separate)
    ├── Home.md
    ├── Getting-Started.md
    └── FAQ.md

Инструменты:
  - GitHub/GitLab wiki = быстрые заметки
  - docs/ = версионируемая документация
  - decisions/ = ADRs
  - Issues = обсуждения

Workflow:
  Problem discovered → RFC в Issues
              ↓
           Обсуждение
              ↓
     Решение принято
              ↓
     Пишется ADR (docs/decisions/)
              ↓
     Код реализуется + обновляется docs/
              ↓
     Pull Request review → merge

Notion Workspace:
├── Documentation (Space)
│   ├── Getting Started (Page)
│   ├── API (Database)
│   └── Architecture (Database)
├── Team (Space)
│   ├── Members (Database)
│   └── Roles (Database)
└── Project Management (Space)
    ├── Roadmap (Timeline database)
    ├── Sprints (Database)
    └── Tasks (Database with relations)

Преимущества:
  - All-in-one (не переключаться)
  - Relations = двусторонние ссылки
  - Встроенные метрики

Недостатки:
  - Не версионируется
  - Lock-in в Notion
  - Non-code friendly

Структура:
Atlassian Cloud
├── Jira
│   ├── Products (Projects)
│   │   ├── Product A (Board)
│   │   │   ├── Sprint 1
│   │   │   ├── Sprint 2
│   │   │   └── Backlog
│   │   └── Product B
│   └── Shared Services
│
└── Confluence
    ├── Products space
    │   ├── Product A docs
    │   ├── Product B docs
    │   └── Shared
    ├── Engineering space
    │   ├── Architecture
    │   ├── Deployment
    │   └── Onboarding
    ├── Management space
    │   ├── OKRs
    │   ├── Strategy
    │   └── Processes
    └── Knowledge base space

Интеграция:
  - Jira issue ↔ Confluence page
  - Macros подтягивают метрики
  - Permissions по space
  - Version control встроен

Workflow:
  1. Requirement в Confluence
  2. Specification (Confluence page)
  3. Jira Epic создана
  4. Issues в Jira (с ссылкой на Confluence)
  5. PR review
  6. Documentation updated (Confluence)
  7. Release (versioning)

Архитектура:
Public (для клиентов/разработчиков):
  docs.company.com (Docusaurus)
  ├── Getting Started
  ├── API Reference (auto-generated)
  ├── Guides
  ├── Blog (updates)
  └── Versioned docs (v1.0, v2.0, ...)

Internal (для команды):
  Internal Wiki (GitHub wiki)
  ├── How-tos
  ├── Processes
  ├── Decision logs (ADRs)
  └── FAQ

Knowledge Base:
  notion.so/kb (Notion)
  ├── Database: Questions (с answers)
  ├── Database: Team Knowledge
  └── Database: Resources

Code:
  GitHub repository
  ├── Code
  ├── README.md
  ├── CONTRIBUTING.md
  └── docs/ (versioned with code)

Workflow:
  1. User asks question
  2. Answer goes to Notion KB
  3. Popular answers → GitHub wiki
  4. Structured docs → Docusaurus docs/
  5. Decision → ADR + GitHub

Из Confluence → В Docusaurus:
1. Export Confluence spaces (XML)
2. Pandoc: XML → Markdown
3. Fix formatting
4. Setup Docusaurus
5. Import markdown
6. Test и deploy

Из GitHub wiki → В Docusaurus:
1. Clone wiki (git clone wiki.git)
2. Copy *.md в docs/
3. Fix relative links
4. Setup Docusaurus
5. Test и deploy

Из Notion → В Markdown:
1. Export pages (HTML)
2. Pandoc: HTML → Markdown
3. Manual cleanup
4. Fix tables и formatting
5. Commit to git

Важно: Всегда версионировать перед миграцией!

Public Docs:
  → Docusaurus (docs.company.com)
  ← Красивая, SEO, версионирована

Internal Docs:
  → GitHub wiki / GitLab wiki
  ← Процессы, how-tos, FAQ

Decisions:
  → ADR в GitHub
  ← Архитектурные решения, контроль версий

Knowledge Base:
  → Notion (если нужна структурированность)
  → или Wiki (если простота)

Project Management:
  → Issues (GitHub/GitLab)
  ← Если код близко
  → Jira (если большая организация)

Real-time:
  → Slack (не документировать!)
  → Обсуждения в Issues/Comments