Руководство администратора по ГОСТ 19.505-79

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Руководителю Аналитику Техническому писателю

Руководство администратора

ГОСТ

Основано на ГОСТ 19.505-79.

Руководство администратора о том, как создавать и блокировать учётные записи, назначать роли, смотреть аудит, настраивать права доступа, подключать интеграции с AD/LDAP, обновлять лицензию, настраивать резервное копирование на уровне приложения (не файлов сервера). Отличие от системного программиста: админ работает через интерфейс или высокоуровневые скрипты, не лезет в конфиги ОС и порты. Отличие от оператора: админ не вводит заявки и не формирует отчёты, он управляет системой сверху.

Администратор системы управляет доступом, пользователями, лицензиями, глобальными настройками всей системы, но может не лезть в её внутреннее устройство как программист.

1. Вводный обзор стандарта ГОСТ 19.505-79

Параметр	Значение
Полное наименование	Руководство оператора. Требования к содержанию и оформлению
Номер стандарта	ГОСТ 19.505–79 (с Изменением №1 от 1981 г., переиздание 1987 г.)
Статус	Действующий (в части применимости к документации legacy-систем и при необходимости соответствия нормам ГОСТ в госсекторе)
Аналог СЭВ	СТ СЭВ 2096–80
Дата введения	01.01.1980
Основной нормативный документ	ГОСТ 19.101–77 (классификация программных документов) и ГОСТ 19.105–78 (общие требования к оформлению программной документации)

1.1. Назначение стандарта

Стандарт определяет минимальные требования к содержанию и структуре документа «Руководство оператора», предназначенного для персонала, эксплуатирующего программу в штатном режиме.

Ключевые цели:

Обеспечить ясное, однозначное и воспроизводимое описание последовательности действий при эксплуатации ПО;
Свести к минимуму риск ошибок при запуске и управлении системой;
Упростить обучение новичков и поддержку в аварийных ситуациях.

1.2. Область применения

Программные продукты, разрабатываемые по требованиям российских госстандартов (например, в госзаказах, оборонных проектах, интеграциях с ЕГАИС, ЕИС, ГИС);
Образовательные курсы по техническому письму и документированию ПО;
Реинжиниринг legacy-систем (документирование «вдогонку»);
Внутренние регламенты компаний, ориентированных на качество документации (особенно при работе с критически важными системами — банки, ЖКХ, ТЭК).

Примечание: Хотя ГОСТ формулирует требования именно к Руководству оператора, его логика применима и к сопутствующим документам — в том числе к Руководству администратора, Руководству по установке, Руководству по настройке. Существенной разницей является целевая аудитория и глубина технических деталей.

2. Структура документа согласно ГОСТ 19.505-79

Стандарт предписывает четыре обязательных раздела:

№	Наименование раздела	Обязательность	Краткое содержание
1	Назначение программы	✅ Обязательно	Функциональное описание, цели использования, ограничения области применения
2	Условия выполнения программы	✅ Обязательно	Требования к «железу», ПО, окружению (ОС, зависимости, лицензии, версии)
3	Выполнение программы	✅ Обязательно	Пошаговая инструкция: запуск, управление, остановка, параметры, ключи, интерактивные команды
4	Сообщения оператору	✅ Обязательно	Список всех возможных сообщений (информационных, предупреждающих, ошибок), их интерпретация и действия

Дополнительно (необязательно, но рекомендуется):

Аннотация и Содержание — формально обязательны согласно ГОСТ 19.105–78;

Приложения — для вспомогательных данных (например: таблицы кодов возврата, форматы логов, конфигурационные шаблоны);

Глоссарий — особенно при работе с узкоспециализированной терминологией.

📌 Важно: Стандарт позволяет объединять разделы или вводить новые, если это обосновано спецификой системы. Например, для высоконагруженной распределённой системы целесообразно выделить:

Раздел 5. Мониторинг и диагностика

Раздел 6. Обновление и резервное копирование

Раздел 7. Безопасность и аудит

3. Пошаговое руководство по составлению Руководства администратора

Шаг 1. Определите целевую аудиторию

Критерий	Оператор	Администратор
Уровень экспертизы	Пользователь с базовыми ИТ-навыками	Системный администратор / DevOps / SRE
Основные задачи	Запуск, ввод-вывод данных, штатное завершение	Установка, настройка, масштабирование, резервирование, диагностика сбоев
Ожидаемые знания	Интерфейс ОС, командная строка (базово)	Сети, ОС (Linux/Windows Server), контейнеризация, CI/CD, мониторинг

→ Следовательно, Руководство администратора должно:

Содержать технические детали (версии пакетов, пути к файлам, права доступа, форматы конфигов);
Включать диагностические процедуры (анализ логов, проверка сервисов, метрики);
Ссылаться на внешние источники (документация СУБД, мидлвара, облачной платформы);
Предоставлять готовые команды (bash, PowerShell, SQL, REST-запросы).

Шаг 2. Структурируйте документ (рекомендуемая модификация ГОСТ)

Раздел	Обязательность	Комментарий
1. Назначение и область применения	✅	Расширенная версия ГОСТ-раздела: включить сценарии использования и не сценарии (что система не делает).
2. Требования к окружению	✅	Аппаратные, ПО (ОС, runtime, зависимости), сетевые (порты, TLS, firewall), лицензионные.
3. Установка и первоначальная настройка	✅	Пошагово: от подготовки хоста до проверки работоспособности.
4. Конфигурация	✅	Все конфигурационные файлы: структура, параметры, примеры, рекомендации.
5. Управление жизненным циклом	✅	Запуск/остановка/перезагрузка, обновление, откат, миграции БД.
6. Мониторинг и диагностика	✅	Метрики, логи, алерты, инструменты, «симптомы → причины».
7. Резервное копирование и восстановление	✅	Политики, процедуры, проверка целостности.
8. Безопасность	✅	Рекомендации по hardening, управление доступом, аудит, сертификаты.
9. Сообщения и коды ошибок	✅	Таблица: код → текст → возможные причины → действия.
Приложения	⚠️ Рекомендуется	Примеры конфигов, схемы архитектуры, диаграммы потоков данных.

✅ Обязательные по смыслу разделы (даже если ГОСТ их не называет отдельно):

Установка

Конфигурация

Ошибки и диагностика

Резервное копирование

Шаг 3. Заполните каждый раздел — рекомендации по содержанию

3.1. Назначение и область применения

Укажите:
- Какие бизнес-задачи решает система.
- Какие роли используют её (типы пользователей: аналитик, админ, интегратор).
- Как система вписывается в ИТ-ландшафт (например: «Служит шлюзом между ERP и внешней CRM»).
- Ограничения: не поддерживает TLS 1.0, не работает на 32-битных ОС, не интегрируется с X.

3.2. Требования к окружению

Подайте в виде таблиц — для читаемости и валидации.

Пример:

Категория	Минимум	Рекомендуется	Комментарии
CPU	2 ядра	4+ ядра	Для production-нагрузки `>`100 RPS
RAM	4 ГБ	8–16 ГБ	+2 ГБ на каждый экземпляр СУБД
ОС	Ubuntu 20.04 LTS	Ubuntu 22.04 LTS	Поддержка до 2027 г.
Docker	20.10+	24.0+	Требуется `cgroup v2`
Java	OpenJDK 11	OpenJDK 17 LTS	`JAVA_HOME` должен быть установлен

❗ Не указывайте «любой современный браузер» — это ошибка. Укажите конкретные версии и режимы (Chrome ≥115, без блокировки third-party cookies).

3.3. Установка и первоначальная настройка

Разбейте на этапы:
1. Подготовка хоста (настройка времени, локали, swap, sysctl)
2. Установка зависимостей (через apt, yum, brew, scoop)
3. Деплой (бинарник / Docker / Helm / Ansible)
4. Проверка (curl -s http://localhost:8080/health, systemctl status myapp)
Добавьте проверочные шаги после каждого этапа — это критично для автоматизации и CI.

3.4. Конфигурация

Для каждого конфиг-файла укажите:
- Путь по умолчанию
- Формат (YAML/JSON/TOML/INI)
- Пример минимального рабочего варианта
- Таблица всех параметров:
  Параметр Тип По умолчанию Обязательный Описание

📌 Используйте -комментарии в примерах конфигов — но не перегружайте.
✅ Хорошо: # max_connections = 100 # рекомендуется 2×CPU для OLTP
❌ Плохо: # это параметр, который влияет на соединения (см. документацию PostgreSQL)

3.5. Управление жизненным циклом

Для каждой операции (start, stop, restart, update, rollback) дайте:
- Команду (с флагами)
- Ожидаемое время выполнения
- Признаки успеха/неудачи (код возврата, лог-сообщение)
- Влияние на сервис (доступность API, RTO/RPO)

3.6–3.8. Мониторинг, резервное копирование, безопасность

Мониторинг:
- Какие метрики собирать (http_requests_total, jvm_gc_pause_seconds)
- Пороги тревог (error_rate > 1% за 5 мин)
- Как проверить «вручную» (curl -f http://metrics:9090/metrics | grep uptime)
Резервное копирование:
- Типы бэкапов (полн./инкр./лог.)
- Частота
- Где хранить (локально/в облаке/на ленте)
- Как проверить целостность (pg_checksums, tar -tzf backup.tar.gz)
Безопасность:
- Hardening: disable SSH password auth, set nosuid on /tmp
- RBAC: какие роли есть (admin, backup, readonly), как назначать
- Аудит: где логируются действия (/var/log/myapp/audit.log, JSON-формат)

3.9. Сообщения и коды ошибок

Формат таблицы:

Код	Уровень	Текст	Причина	Действие
`ERR-1001`	`FATAL`	`DB connection refused`	СУБД не запущена / неверный порт	1. `systemctl status postgresql` 2. Проверить `database.url` в `config.yml`
`WARN-2048`	`WARN`	`Cache miss ratio > 90%`	Недостаточный размер кэша	Увеличить `cache.size_mb` в конфиге

✅ Рекомендуется привязывать коды к версии API/движка: ERR-1001 @v2.3+

4. Типичные ошибки и как их избежать

Ошибка	Почему плохо	Как исправить
«Как у нас в голове» — инструкция написана разработчиком, не проверена админом	Админ не знает внутренних соглашений; шаги пропущены	Проводите техническое ревью с целевой аудиторией (devs + ops)
Отсутствие «проверочных точек»	Невозможно понять — где сломалось?	После каждого шага — команда проверки (`systemctl is-active`, `netstat -tlnp`)
Примеры «из воздуха»	Не соответствуют реальному поведению (особенно после обновления)	Примеры должны быть выполнены реально и зафиксированы (например, через `script` или CI-логи)
Нет версионности	Админ не знает — подходит ли документ к его версии	В шапке — точная версия ПО и документа: `Руководство администратора v1.4 (для SystemX v3.2.1)`
Смешение ролей (оператор + админ)	Оператор перегружен деталями, админ не находит нужного	Чёткое разделение: Руководство оператора — для ежедневных операций; Руководство администратора — для maintenance. Ссылки между ними — допустимы.
Отсутствие диаграмм	Сложно понять топологию связей	Добавьте UML Deployment Diagram или простую схему в Graphviz/Mermaid
Игнорирование «человеческого фактора»	Инструкции без учёта стресса: «в случае отказа кластера — см. Приложение Г»	В разделе ошибок — пошаговый алгоритм для дежурного ночью:

Убедитесь, что проблема не локальная (проверьте с другого хоста)
Посмотрите /var/log/myapp/current.log — последние 50 строк
Если OOMKilled — увеличьте memory.limit_in_bytes
Если повторяется — вызовите дежурного разработчика по телефону X |

5. Руководство администратора

Система: Orion Данные Mesh Gateway, версия 2.1.3

Шлюз для федеративного доступа к данным в гетерогенной ИТ-среде (поддержка REST, GraphQL, JDBC, S3-совместимых хранилищ)

Версия документа: ADM-GUIDE-2.1.3-2025-11
Целевая аудитория: системные администраторы, DevOps-инженеры, SRE
Совместимость: Только с версиями ПО 2.1.x. Для 2.0.x см. ADM-GUIDE-2.0.

5.1 Назначение и область применения

Orion Данные Mesh Gateway — middleware-сервис, обеспечивающий:

Единый API-интерфейс (GraphQL + REST) к разнородным источникам данных (БД, хранилища, внешние API);
Политики доступа на уровне полей (field-level RBAC);
Аудит запросов и метрики производительности;
Автоматическое кэширование и проксирование.

Поддерживаемые сценарии

Сценарий	Поддерживается	Комментарий
Доступ к PostgreSQL через JDBC	✅	Поддержка SSL, connection pooling
Чтение CSV из MinIO	✅	Авто-парсинг CSV/Parquet
Запрос внешнего REST API с OAuth2	✅	Поддержка `client_credentials` flow
Запись в ClickHouse	✅	Только bulk-операции (через очередь)

Не поддерживаемые сценарии

Доступ к локальным файлам напрямую (file://) — запрещён политикой безопасности;
Использование в embedded-режиме (как библиотека);
Работа без аутентификации (даже в dev-режиме требуется --allow-anonymous флаг).

5.2 Требования к окружению

5.2.1 Аппаратные требования

Компонент	Минимум	Production-рекомендация
CPU	2 vCPU	4+ vCPU (Intel/AMD 2018+)
RAM	4 ГБ	8–16 ГБ (в зависимости от числа источников)
Диск	10 ГБ SSD (ОС + логи)	100+ ГБ NVMe (с учётом кэша и очередей)
Сеть	100 Мбит/с	1 Гбит/с, latency < 2 мс до БД

5.2.2 Программные требования

Компонент	Версия	Комментарий
ОС	Ubuntu 20.04 / 22.04 LTS, RHEL 8+	Поддержка `systemd`, `cgroup v2`
Java	OpenJDK 17 (LTS)	`JAVA_HOME` обязателен; OpenJ9 не поддерживается
Docker (опционально)	20.10+	Требуется `docker-compose v2.10+` для dev-сборки
TLS	OpenSSL 1.1.1+	Поддержка TLS 1.2+; TLS 1.0/1.1 — отключены по умолчанию

5.2.3 Сетевые требования

Порт	Протокол	Назначение	Направление
`8080/tcp`	HTTP	Основной API (GraphQL/REST)	входящий
`8081/tcp`	HTTP	Admin UI и метрики (`/actuator`)	входящий (ограничен IP)
`9090/tcp`	HTTP	Prometheus endpoint	входящий (только с `monitoring` subnet)
`5432/tcp`	TCP	Подключение к PostgreSQL (outbound)	исходящий
`443/tcp`	HTTPS	OAuth2, внешние API	исходящий

🔐 Все входящие порты должны быть защищены через reverse proxy (Nginx/Traefik) с TLS и WAF.

5.3 Установка и первоначальная настройка

5.3.1 Подготовка хоста (Ubuntu 22.04)

# 1. Установка зависимостей
sudo apt update && sudo apt install -y \
  openjdk-17-jre-headless \
  curl wget gnupg \
  systemd-journal-remote

# 2. Проверка Java
java -version
# Должно: openjdk version "17.0.12" 2024-07-16

# 3. Создание пользователя
sudo useradd --Система --home /opt/orion --shell /bin/false orion
sudo mkdir -p /opt/orion/{Данные,logs,config}
sudo chown -R orion:orion /opt/orion

✅ Проверка: id orion → uid=998(orion) gid=998(orion) groups=998(orion)

5.3.2 Установка бинарника

# 4. Загрузка
wget https://pkg.orion.dmgw.example/releases/orion-gateway-2.1.3.tar.gz \
  -O /tmp/orion.tar.gz

# 5. Проверка контрольной суммы
echo "sha256: 3f7b...d8a1  /tmp/orion.tar.gz" | sha256sum -c

# 6. Распаковка
sudo tar -xzf /tmp/orion.tar.gz -C /opt/orion --strip-components=1
sudo chown -R orion:orion /opt/orion

5.3.3 Настройка systemd-сервиса

Файл: /etc/systemd/system/orion-gateway.service

[Unit]
Description=Orion Данные Mesh Gateway
After=Сеть.target

[Service]
User=orion
Group=orion
WorkingDirectory=/opt/orion
ExecStart=/opt/orion/bin/orion-gateway \
  --config /opt/orion/config/orion.yml \
  --log-path /opt/orion/logs/orion.log
Restart=on-failure
RestartSec=10
Environment=JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC"

[Install]
WantedBy=multi-user.target

✅ Проверка после sudo systemctl daemon-reload && sudo systemctl start orion-gateway:

systemctl is-active orion-gateway  # → active
journalctl -u orion-gateway -n 20 --no-pager | grep "Started"
# Должно: ... INFO  c.o.g.OrionApplication — Started OrionApplication...
curl -s http://localhost:8081/actuator/health | jq .status
# → "UP"

5.4 Конфигурация

5.4.1 Основной файл: `/opt/orion/config/orion.yml`

Пример минимальной рабочей конфигурации:

server:
  port: 8080
  admin-port: 8081
  ssl:
    enabled: false  # ← д.б. true в prod!
    # key-store: /etc/ssl/orion.p12

auth:
  jwt:
    issuer: "https://auth.orion.example"
    jwks-uri: "https://auth.orion.example/.well-known/jwks.json"
  anonymous-access: false  # ← разрешить только в dev

datasources:
  - name: "sales_db"
    type: "postgres"
    url: "jdbc:postgresql://pg-main:5432/sales"
    username: "${PG_USER}"  # ← из env
    password: "${PG_PASS}"
    pool:
      max-size: 20
      timeout-ms: 3000

cache:
  type: "caffeine"
  max-entries: 10000
  ttl-minutes: 15

5.4.2 Таблица ключевых параметров

Параметр	Тип	По умолчанию	Обяз.	Описание
`server.port`	`int`	`8080`	❌	Порт основного API
`auth.anonymous-access`	`bool`	`false`	❌	Разрешить запросы без JWT
`datasources[*].name`	`string`	—	✅	Уникальный ID источника (исп. в GraphQL)
`datasources[*].url`	`string`	—	✅	JDBC/HTTP/S3 URL
`cache.ttl-minutes`	`int`	`10`	❌	Время жизни кэша (0 = отключить)
`metrics.prometheus.enabled`	`bool`	`true`	❌	Включить `/actuator/prometheus`

🔐 Безопасность: Пароли нельзя хранить в orion.yml. Используйте:

Переменные окружения (PG_PASS=...)

Vault-интеграцию (vault://secret/pg/sales)

systemd EnvironmentFile=

5.5 Управление жизненным циклом

Операция	Команда	Время	Признак успеха
Запуск	`sudo systemctl start orion-gateway`	≤5 сек	`systemctl is-active orion-gateway` = `active`
Остановка	`sudo systemctl stop orion-gateway`	≤10 сек	Graceful shutdown: `... — Closing DataSource...` в логах
Перезапуск	`sudo systemctl restart orion-gateway`	≤15 сек	Новый PID в `systemctl status`
Обновление	1. Остановить 2. Заменить бинарники 3. Запустить	≤2 мин	`curl /actuator/info \| jq .build.version` = `2.1.3`
Откат	Аналогично, но с архивом `orion-gateway-2.1.2.tar.gz`	≤2 мин	Версия в `/actuator/info` соответствует ожидаемой

⚠️ Важно:

Перед обновлением — сделать бэкап конфигов и БД метаданных (если используется embedded H2);

При major-апдейте (2.1 → 3.0) — обязательно свериться с MIGRATION.md.

5.6 Мониторинг и диагностика

5.6.1 Ключевые метрики (Prometheus)

Метрика	Тип	Описание	Порог тревоги
`http_server_requests_seconds_count{uri="/graphql"}`	counter	RPS на GraphQL	>500 sustained
`datasource_connection_acquired_seconds_max{datasource="sales_db"}`	gauge	Время получения коннекта	>1.0 с
`jvm_memory_used_bytes{area="heap"}`	gauge	Использовано heap	>85% от `-Xmx`
`cache_miss_ratio`	gauge	Доля miss’ов в кэше	>0.3

Пример алерта (Alertmanager):

- alert: HighDBLatency
  expr: datasource_connection_acquired_seconds_max > 1.0
  for: 2m
  labels:
    severity: warning
  annotations:
    summary: "High DB latency in {{ $labels.datasource }}"

5.6.2 Анализ логов

Формат лога (JSON, logs/orion.log):

{
  "ts": "2025-11-11T10:22:45.123Z",
  "level": "ERROR",
  "logger": "c.o.g.d.DataSourceExecutor",
  "msg": "Query failed",
  "error": "Connection refused",
  "datasource": "sales_db",
  "queryId": "q-77a8b9c0"
}

Диагностический чек-лист при падении API:

systemctl status orion-gateway — жив ли процесс?
journalctl -u orion-gateway -n 100 --no-pager | grep -i error
curl -s http://localhost:8081/actuator/health — какие компоненты down?
ss -tuln | grep ':8080' — слушает ли сокет?
dmesg -T | tail -20 — OOM/Kill?

5.7 Резервное копирование и восстановление

5.7.1 Что бэкапить

Компонент	Путь	Частота	Тип бэкапа
Конфигурация	`/opt/orion/config/`	Перед каждым изменением	Полный
Метаданные (если embedded H2)	`/opt/orion/Данные/metadata.mv.db`	Ежедневно	Полный
Кэш	—	Не требуется	—
Логи	`/opt/orion/logs/`	По ротации	Архив (7 дней)

5.7.2 Пример скрипта бэкапа

#!/bin/bash
set -euo pipefail
BACKUP_DIR="/backups/orion/$(date +%Y%m%d_%H%M)"
mkdir -p "$BACKUP_DIR"

tar -czf "$BACKUP_DIR/config.tar.gz" -C /opt/orion config/
cp /opt/orion/Данные/metadata.mv.db "$BACKUP_DIR/"

# Проверка целостности
tar -tzf "$BACKUP_DIR/config.tar.gz" >/dev/null && echo "✅ Config OK"
[ -f "$BACKUP_DIR/metadata.mv.db" ] && echo "✅ Metadata copied"

# Отправка в MinIO
mc cp "$BACKUP_DIR/" minio/backups/orion/

5.7.3 Восстановление

Остановить сервис
Заменить config/ и Данные/metadata.mv.db из бэкапа
Запустить

Проверить:

curl http://localhost:8081/actuator/health | jq '.details."metadata-db"'
# → {"status":"UP"}

5.8 Безопасность

Мера	Команда/Настройка	Обоснование
Отключить анонимный доступ	`auth.anonymous-access: false`	Соответствие ISO 27001
Ограничить admin-порт	`iptables -A INPUT -p tcp --dport 8081 ! -s 10.10.0.0/24 -j DROP`	Только из сети мониторинга
Включить TLS	`server.ssl.enabled: true` + корректный `key-store`	Защита от MITM
Настроить аудит	`audit.enabled: true`, `audit.log-path: /var/log/orion/audit.log`	Требование 152-ФЗ
Обновлять зависимости	`./bin/orion-gateway --list-vulns` (еженедельно)	Устранение CVE (например, Log4j)

5.9 Сообщения и коды ошибок

Код	Уровень	Текст	Причина	Действие
`ODM-1001`	`FATAL`	`Failed to bind to port 8080: Address already in use`	Другой процесс слушает порт	`lsof -i :8080`, остановить конфликтующий сервис
`ODM-2048`	`ERROR`	`JWT signature verification failed`	Неверный `jwks-uri` или ключ повёрнут	Проверить `auth.jwks-uri`, синхронизировать время
`ODM-3012`	`WARN`	`Cache miss ratio=0.78 (>0.5)`	Неоптимальные TTL или запросы	Увеличить `cache.ttl-minutes`, проанализировать GraphQL-запросы
`ODM-5500`	`FATAL`	`DataSource 'sales_db' unreachable after 3 retries`	Сетевой разрыв / БД down	Проверить `ping pg-main`, `telnet pg-main 5432`, логи PostgreSQL

📌 Все ошибки логируются с errorId, который можно искать в logs/orion.log или централизованном ELK.

6. Проверка Руководства администратора

Используйте этот список на этапе ревью перед публикацией.

№	Критерий	Применимо?	Комментарий/Исправление
1	Указана точная версия ПО, для которой актуален документ	☐	Например: `v2.1.3 (build 21345)`
2	Есть аннотация и содержание (в соответствии с ГОСТ 19.105)	☐	Даже если в Markdown — `## Содержание` с якорями
3	Разделы соответствуют четырём базовым по ГОСТ (назначение, условия, выполнение, сообщения)	☐	Дополнения — допустимы, но базовые — обязательны
4	Все команды и примеры проверены на реальной системе (не «на коленке»)	☐	Лучше — автоматизированная проверка в CI
5	Есть проверочные шаги после каждого критического действия	☐	«После установки — выполните `curl /health`»
6	Конфиги приведены в рабочем виде (не абстрактные `{{param}}`)	☐	Можно использовать placeholder’ы, но с пояснением, как подставлять
7	Указаны ограничения и не поддерживаемые сценарии	☐	Это снижает количество L1-тикетов
8	Все пути — абсолютные, без `~/` или `.\`	☐	`/opt/orion/config/orion.yml`, не `./config.yml`
9	Есть диагностический чек-лист для типовых сбоев	☐	Особенно важно для дежурных
10	Упомянуты политики безопасности и соответствие нормам (ГОСТ, 152-ФЗ, ISO 27001)	☐	Даже если «не требуется» — повышает доверие
11	Документ версионирован и имеет дату публикации	☐	`ADM-GUIDE-2.1.3-2025-11`
12	Есть ссылки на сопутствующие документы: Руководство пользователя, API Spec, MIGRATION.md	☐	В разделе См. также

📌 Финальная рекомендация:
Перед выпуском — проведите «слепой тест»: отдайте документ коллеге-администратору (не участвовавшему в разработке), дайте задачу: «Установи систему с нуля по этой инструкции». Замерьте время и количество вопросов. Идеал — 0 вопросов и ≤150% от expert-time.

См. также

Другие статьи этого же раздела в боковом меню (как на странице «О разделе»).