Стандарт документации

Версия: 2.0.0
Дата: 2025-11-24
Статус: АКТИВНЫЙ
Назначение: Универсальные принципы создания документов
Приоритет: ВЫСОКИЙ — применяется ко всем документам

СОДЕРЖАНИЕ

1. Исполнительное резюме
2. Документ как система
3. Пять типов документов
4. Пять структурных блоков
5. Жизненный цикл
6. Версионирование
7. Критерии качества
8. Связи с другими документами

1. ИСПОЛНИТЕЛЬНОЕ РЕЗЮМЕ

Цель: Определить универсальные принципы документации через призму методологии.

Ключевые решения:
- 5 типов документов по функции (что делает)
- 5 структурных блоков (из чего состоит)
- 3 статуса жизненного цикла
- Семантическое версионирование

Результат: Система документации, выведенная из методологии срезов.

2. ДОКУМЕНТ КАК СИСТЕМА

Документ — это система. Применяем методологию 8 срезов:

3. ПЯТЬ ТИПОВ ДОКУМЕНТОВ

Классификация по функции

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

Выбор типа

Документ отвечает на вопрос:

ПОЧЕМУ так?        → Концепция
КАК ДОЛЖНО быть?   → Норма
ЧТО ЕСТЬ?          → Описание
КАК ДЕЛАТЬ?        → Инструкция
ЧТО БЫЛО?          → Запись

Детали каждого типа

Концепция

Функция: Объясняет принципы и философию.

Содержит:
- Проблему и её контекст
- Решение и обоснование
- Принципы и подходы
- Связь с другими концепциями

Примеры: Методология, философия продукта, vision.

Норма

Функция: Устанавливает правила и требования.

Содержит:
- Что регламентируется
- Правила (разрешено/запрещено/обязательно)
- Критерии соответствия
- Последствия нарушений

Примеры: Стандарты, политики, регламенты, SLA.

Описание

Функция: Описывает существующее состояние.

Содержит:
- Структуру (компоненты, связи)
- Характеристики
- Классификации
- Определения терминов

Примеры: Архитектура системы, справочник API, глоссарий, каталог.

Инструкция

Функция: Учит выполнять действия.

Содержит:
- Цель действия
- Предусловия
- Пошаговый алгоритм
- Ожидаемый результат
- Что делать при ошибках

Примеры: Процедуры, гайды, туториалы, runbook.

Запись

Функция: Фиксирует произошедшие события.

Содержит:
- Дату/время события
- Что произошло
- Кто участвовал
- Результат/последствия

Примеры: Changelog, журнал решений, incident report, meeting notes.

4. ПЯТЬ СТРУКТУРНЫХ БЛОКОВ

Структура документа

Каждый документ состоит из 5 блоков:

ДОКУМЕНТ
│
├── 1. МЕТАДАННЫЕ     — идентификация документа
├── 2. НАВИГАЦИЯ      — ориентация по содержимому
├── 3. РЕЗЮМЕ         — суть за 30 секунд
├── 4. ТЕЛО           — основное содержимое
└── 5. СВЯЗИ          — контекст и зависимости

Детали каждого блока

1. Метаданные

Назначение: Идентификация документа.

Формат:

# Название документа

**Версия:** X.Y.Z
**Дата:** YYYY-MM-DD
**Статус:** ЧЕРНОВИК | АКТИВНЫЙ | АРХИВНЫЙ
**Назначение:** Одно предложение
**Приоритет:** КРИТИЧЕСКИЙ | ВЫСОКИЙ | СРЕДНИЙ | НИЗКИЙ

Обязательность: Да, всегда.

2. Навигация

Назначение: Ориентация по документу.

Формат:

# СОДЕРЖАНИЕ

1. Раздел 1
2. Раздел 2
...
N. Связи с другими документами

Обязательность: Да, если больше одного раздела.

3. Резюме

Назначение: Понять суть за 30 секунд.

Формат:

# ИСПОЛНИТЕЛЬНОЕ РЕЗЮМЕ

**Цель:** Одно предложение — что решает документ.

**Ключевые решения:**
- Пункт 1
- Пункт 2
- Пункт 3

**Результат:** Одно предложение — что получаем.

Обязательность: Да, всегда.

4. Тело

Назначение: Основное содержимое документа.

Содержит: Разделы согласно содержанию, от общего к частному.

Неизменяемый блок (если есть критичные принципы):

⚠️ НЕИЗМЕНЯЕМЫЙ БЛОК
Изменение требует новой мажорной версии.

Обязательность: Да, всегда.

5. Связи

Назначение: Контекст документа в системе.

Формат:

# СВЯЗИ С ДРУГИМИ ДОКУМЕНТАМИ

## Входящие связи
На этот документ ссылаются:
- Документ 1
- Документ 2

## Исходящие связи
Этот документ ссылается на:
- Документ A
- Документ B

Обязательность: Да, всегда.

5. ЖИЗНЕННЫЙ ЦИКЛ

Три статуса

ЧЕРНОВИК → АКТИВНЫЙ → АРХИВНЫЙ

Процесс создания

1. СОЗДАНИЕ
   Определить тип, назначение, структуру
   → Статус: ЧЕРНОВИК

2. РАЗРАБОТКА
   Написать содержание, итерации
   → Статус: ЧЕРНОВИК

3. ВАЛИДАЦИЯ
   Проверить по критериям качества
   → Статус: ЧЕРНОВИК

4. УТВЕРЖДЕНИЕ
   Документ готов к использованию
   → Статус: АКТИВНЫЙ

5. ПОДДЕРЖКА
   Обновления с версионированием
   → Статус: АКТИВНЫЙ

6. УСТАРЕВАНИЕ
   Заменён или больше не нужен
   → Статус: АРХИВНЫЙ

Переходы

6. ВЕРСИОНИРОВАНИЕ

Формат

Semantic Versioning: MAJOR.MINOR.PATCH

MAJOR — несовместимые изменения (меняется смысл)
MINOR — новое содержание (совместимо)
PATCH — исправления (опечатки, уточнения)

Правила изменения

Правила

• Первая версия: 1.0.0
• При MAJOR сбрасываются MINOR и PATCH до 0
• При MINOR сбрасывается PATCH до 0
• Дата обновляется при любом изменении версии

7. КРИТЕРИИ КАЧЕСТВА

Валидация по 4 категориям

7.1 Полнота

• [ ] Все 5 блоков присутствуют
• [ ] Все разделы из содержания раскрыты
• [ ] Нет пустых секций
• [ ] Метаданные заполнены

7.2 Логичность

• [ ] Порядок от общего к частному
• [ ] Нет противоречий
• [ ] Термины последовательны
• [ ] Тип соответствует содержанию

7.3 Практичность

• [ ] Информация применима
• [ ] Примеры понятны
• [ ] Инструкции выполнимы
• [ ] Критерии измеримы

7.4 Оформление

• [ ] Единообразное форматирование
• [ ] Корректные таблицы и списки
• [ ] Нет опечаток
• [ ] Читаемая структура

Быстрый чек-лист

□ Метаданные заполнены
□ Содержание соответствует разделам
□ Резюме есть
□ Связи указаны
□ Тип документа верный

8. СВЯЗИ С ДРУГИМИ ДОКУМЕНТАМИ

Входящие связи

На этот документ ссылаются:
- Все документы системы (как стандарт оформления)

Исходящие связи

Этот документ ссылается на:
- found/concepts/METHODOLOGY.md — методология (8 срезов)

Иерархия

METHODOLOGY.md      ← Как описывать системы
    ↓
DOCUMENTATION.md    ← Как оформлять документы (этот документ)

Результат: Система документации, выведенная из методологии срезов.