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

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

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

Руководство оператора

ГОСТ

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

Оператор - это человек, который сидит за компьютером и активно работает с программой каждый день (вводит данные, формирует отчёты, нажимает кнопки).

Руководство оператора - это документ о том, как выполнять конкретные операции — пошагово, с картинками интерфейса. "Чтобы создать заявку: (1) нажмите кнопку "Новая заявка", (2) заполните поле "Клиент", (3) нажмите "Сохранить". Ожидаемый результат: заявка появится в списке". Здесь не пишут, как настраивать сервер (это к администратору) и не объясняют внутреннее устройство программы (это к программисту).

1. Введение в стандарт

ГОСТ 19.505–79 — советский государственный стандарт, входящий в Единую систему программной документации (ЕСПД), утверждённый постановлением Госстандарта СССР № 74 от 12 января 1979 г., с введением с 1 января 1980 г. Стандарт полностью соответствует международному/межгосударственному СТ СЭВ 2096–80.

1.1. Назначение документа «Руководство оператора»

«Руководство оператора» — нормативно-технический документ, предназначенный для лиц, непосредственно управляющих программой в процессе её эксплуатации (операторов, сисадминов, дежурных инженеров). Его цель — обеспечить корректный и безопасный запуск, управление, мониторинг и завершение работы программы в реальных условиях эксплуатации.

⚠️ Термин «оператор» в контексте стандарта — любой пользователь с правами управления жизненным циклом программы: запуск, пауза, останов, перезапуск, обработка ошибок.

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

Стандарт применяется при разработке программного обеспечения:

для государственных и оборонных заказчиков (в т.ч. в рамках ГОСТ ЕСПД — 19.101–77, 19.105–78 и др.);
в проектах, регулируемых договорами, требующими соблюдения нормативной документации;
в образовательных и методических целях — как эталон структуры эксплуатационной документации.

Хотя ГОСТ имеет статус «не действующий» в РФ (аннулирован в 2002 г.), его требования остаются практически востребованными:

в legacy-проектах;
в интеграционных решениях с государственными информационными системами (ГИС, ЕГАИС, ЕИС, ЕСИА и др.);
в методиках разработки технической документации (в т.ч. в университетских курсах и корпоративных стандартах).

1.3. Нормативные ссылки и требования к оформлению

Согласно п. 1.1 стандарта:

«Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105–78».

ГОСТ 19.105–78 регламентирует:

общий состав программной документации;
структуру программного документа (титульный лист → лист регистрации изменений → аннотация → содержание → основное содержание → приложения → список использованных источников);
правила нумерации разделов и подразделов (десятичная система);
обязательное наличие информационной части (аннотация + содержание).

Таким образом, «Руководство оператора» — формализованный документ, подчинённый строгой структуре и метаданным.

2. Структура документа по ГОСТ 19.505–79

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

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

2.1. Гибкость структуры

ГОСТ допускает (п. 1.2, 2.5, 2.6):

объединение разделов (напр., «Условия выполнения» + «Выполнение» в единый «Подготовка и запуск»);
введение дополнительных разделов («Аварийные процедуры», «Журналирование», «Мониторинг ресурсов»);
иллюстрирование примерами, таблицами, схемами;
вынесение вспомогательных материалов в приложения (лог-файлы, примеры конфигов, коды возврата, скриншоты интерфейсов CLI/GUI).

🔶 Пример допустимых дополнительных разделов:

Работа с резервными копиями

Диагностика производительности

Интеграция с внешними системами

Политики безопасности при эксплуатации

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

Ниже — методически выстроенная последовательность действий для технического писателя или инженера-документалиста. Последовательность учитывает требования ГОСТ 19.505–79 и практику современной технической документации (включая DevOps- и SRE-подходы).

✅ Принцип: «Руководство оператора» — инструкция по управлению состоянием системы в реальном времени.

Шаг 1. Подготовка метаданных и каркаса

Определите идентификатор и наименование программы
Используйте официальное название и версию (согласно ГОСТ 19.101–77):
```
Программа: «X-Engine» (версия 3.2.1, сборка 20251028.1)
Код проекта: XEN-OPS-321
Разработчик: ООО «IT Universe Labs»
```
Создайте базовую структуру документа (в соответствии с ГОСТ 19.105–78):
- Титульный лист
- Лист регистрации изменений
- Аннотация (не более 250 слов)
- Содержание (с нумерацией разделов по ГОСТ)
- Основные разделы (по 19.505–79)
- Приложения (если есть)

📌 Аннотация должна отражать:

цели и задачи программы,

класс решаемых задач,

основную аудиторию операторов,

особенности эксплуатации (непрерывный режим, пакетная обработка и т.п.).

Шаг 2. Наполнение обязательных разделов

2.1. Раздел 1. «Назначение программы»

Что писать:

Функциональное назначение («что решает для пользователя»).
Контекст применения: автономный режим, серверный процесс, микросервис, batch-задача и т.п.
Внешние взаимодействия (API вход/выход, файловые интерфейсы, очереди, БД).
Границы ответственности: что входит в зону управления оператора, что — нет.

Что НЕ писать:

Архитектурные диаграммы (вынести в Описание программы по ГОСТ 19.104–78).
Исходный код или алгоритмы (это — Программа и методика испытаний, ГОСТ 19.301–79).
Маркетинговые формулировки («революционный», «уникальный» и т.п.).

🔍 Проверка качества:
После прочтения раздела 1 оператор должен однозначно понять:
«Можно ли мою задачу решить этим ПО? Кто ещё участвует в процессе? Что я должен контролировать?»

2.2. Раздел 2. «Условия выполнения программы»

Обязательная информация:

Требования к аппаратному обеспечению (мин./макс.):
- CPU (ядра, архитектура: x86_64/aarch64)
- RAM (мин., рекоменд., при пиковой нагрузке)
- HDD/SSD (объём, IOPS, тип файловой системы)
Требования к программному обеспечению:
- ОС (в т.ч. дистрибутивы Linux, версии Windows Server)
- Зависимости (runtime: .NET 8.0, OpenJDK 17, Python 3.11+; контейнер: Docker ≥24.0)
- Сетевые требования (порт, протокол, TLS ≥1.3, DNS-резолвер)
- Внешние сервисы (БД PostgreSQL ≥14, Kafka ≥3.5, внешний LDAP)

⚠️ Важно: указывать конкретные версии, а не «любая актуальная».
Пример недопустимой формулировки:
❌ «Требуется современная СУБД»
✅ «Требуется PostgreSQL 14.7–16.3 с расширением pg_cron. Подключение по TCP/IP (порт 5432, sslmode=require)»

Дополнительно рекомендуется:

Таблицы совместимости (например, matrix OS × runtime);
Диаграмма зависимостей (в приложении);
Проверочные команды («быстрая диагностика окружения»).

Пример блока кода для проверки:

# Проверка минимального окружения для X-Engine
[ $(uname -s) = "Linux" ] || { echo "ОС: только Linux"; exit 1; }
[ $(getconf LONG_BIT) -eq 64 ] || { echo "Требуется 64-битная ОС"; exit 1; }
command -v java >/dev/null || { echo "Отсутствует Java"; exit 1; }
java -version 2>&1 | grep -q '17\|21' || { echo "Требуется OpenJDK 17 или 21"; exit 1; }

2.3. Раздел 3. «Выполнение программы»

Здесь — ядро документа. Структурируйте как цепочку состояний:

Этап	Подэтапы	Что указать
Подготовка	— Установка (если не отдельный документ) — Настройка (конфигурационные файлы, переменные окружения) — Предзапускная проверка (health-check)	Примеры `config.yaml`, `env.example`, схемы валидации
Запуск	— Интерактивный/фоновый режим — Параметры командной строки — Системные службы (`systemd`, `launchd`) — Контейнерный запуск (`docker run`, `podman`)	Точная сигнатура CLI: `xengine start [--mode=batch
Управление	— Команды runtime (pause/resume/shutdown) — Методы IPC (REST API `/control`, `SIGUSR1`, сокет) — Интерфейс CLI/REPL/веб-панель	Таблица команд с: синтаксисом, уровнем доступа, side-effect-ами
Завершение	— Штатное завершение (`SIGTERM` + graceful shutdown) — Аварийная остановка (`SIGKILL`) — Проверка корректного завершения (код возврата, логи)	Коды возврата: `0 — OK`, `1 — ошибка конфигурации`, `2 — timeout`, `128+ — сигнал`

📌 Включайте «как» и «почему»:
«Параметр --grace-period=30s задаёт время, в течение которого система завершает обработку текущих задач перед закрытием соединений. Уменьшение значения ниже 10 с может привести к потере данных в режиме stream».

2.4. Раздел 4. «Сообщения оператору»

Структурируйте как реестр событий, отсортированный по критичности:

Уровень	Код	Текст сообщения	Причина	Действия оператора
`INFO`	`XEN-1001`	`Engine started in batch mode, job queue length: 0`	Штатный запуск	Наблюдать
`WARN`	`XEN-2017`	`Config file /etc/xengine.yaml is world-readable`	Нарушение Безопасность policy	Исправить права: `chmod 640 /etc/xengine.yaml`
`ERROR`	`XEN-3022`	`Connection to PostgreSQL failed: timeout after 5000ms`	Недоступен БД-хост	Проверить сеть, `pg_isready -h db`, повторить через 30 с
`FATAL`	`XEN-4099`	`Required module 'crypto' not loaded (JCE not found)`	Отсутствует Java Cryptography Extension	Установить JCE Unlimited Strength Policy или использовать OpenJDK `≥`17

✅ Обязательно укажите:

формат лог-сообщения (например: [TIMESTAMP][LEVEL][PID][THREAD] CODE: message);

пути к лог-файлам по умолчанию (/var/log/xengine/main.log, journalctl -u xengine);

методы фильтрации (grep -E 'XEN-[34].*' main.log).

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

№	Ошибка	Последствия	Рекомендация
1	Описание для разработчика, а не оператора	Оператор не может понять, что делать, только почему так.	Пишите от лица оператора: «Выполните…», «Проверьте…», «Если видите X — сделайте Y».
2	Отсутствие конкретики в параметрах	Неопределённость → ошибки конфигурации.	Всегда указывайте: тип, единицы измерения, диапазон, значение по умолчанию, пример. Пример: `--batch-size=100 (int, 1–10000, default=100)`
3	Нет кодов возврата или сообщений об ошибках	Затруднена диагностика, необходимость читать исходники.	Выведите полный перечень exit-codes и сообщений в таблице. Ссылайте в логах на код (XEN-XXXX).
4	Объединение с «Руководством пользователя»	Путаница: пользователь `≠` оператор.	Чётко разделяйте: РО — для управления процессом, РП — для работы с функционалом.
5	Отсутствие примеров команд	Теория без практики → медленный onboarding.	Для каждого режима — один полный пример: `xengine start --mode=stream --config=/etc/xengine.yaml --log-level=debug`
6	Не указаны права доступа	Ошибки запуска от `root` vs `xengine` user.	Добавьте раздел «Требования к учётной записи»: UID/GID, группы, capabilities (`CAP_NET_BIND_SERVICE`).

💡 Правило «3-х вопросов» для проверки:
Любой пункт в РО должен отвечать на:

Что я должен сделать?

Как я пойму, что сделал правильно?

Что делать, если пошло не так?

5. Пример: фрагмент «Руководства оператора» для вымышленной системы X-Engine

Система X-Engine — модуль обработки потоковых данных в режиме near real-time.
Приём: JSON по HTTP/2 или Kafka. Обработка: агрегация, фильтрация, обогащение. Выдача: в ClickHouse и S3.
Режимы: batch (пакетный), stream (потоковый), replay (повтор воспроизведения логов).

5.1. Назначение программы

Программа xengine предназначена для выполнения потоковой обработки структурированных событий в распределённой среде. Основные функции:

Приём событий через HTTP-эндпоинт /ingest (POST, JSON array) или потребление из Kafka (топик events.raw);
Применение правил обработки из rules.d/*.yaml;
Формирование агрегатов (минутные/часовые окна);
Запись результатов в ClickHouse (events.enriched) и резервную копию — в S3 (s3://x-bucket/archive/).

Границы ответственности оператора:

Обеспечение доступности xengine, Kafka, ClickHouse, S3;
Мониторинг задержек обработки (lag);
Реакция на аварийные остановки и ошибки записи;
Не входят в зону ответственности: написание правил обработки, изменение схемы БД, развитие API.

5.2. Условия выполнения программы

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

Режим	CPU (ядра)	RAM	Диск	Сеть
`batch` (до 10 тыс. эв/с)	4	8 ГБ	50 ГБ SSD (для temp)	100 Мбит/с
`stream` (до 100 тыс. эв/с)	16	32 ГБ	200 ГБ NVMe + 1 ТБ HDD	1 Гбит/с, `<`1 мс latency

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

ОС: Ubuntu 22.04 LTS / RHEL 9 / AlmaLinux 9 (x86_64)
Java: OpenJDK 17 или 21 (Temurin, Azul Zulu)
Доступ к:
- Kafka 3.5+ (bootstrap.servers, SASL/SCRAM)
- ClickHouse 23.8+ (HTTP interface, user xengine, роль ingest)
- S3-совместимое хранилище (AWS S3, MinIO — endpoint, access/secret key)
Права: пользователь xengine, группа xengine; CAP_NET_BIND_SERVICE (для порта 8080)

Проверка окружения (скрипт `/opt/xengine/bin/env-check.sh`)

#!/bin/bash
set -euo pipefail

echo "🔍 X-Engine Environment Checker (v1.2)"
echo "OS: $(lsb_release -ds 2>/dev/null || cat /etc/os-release | grep PRETTY_NAME)"
echo "Java: $(java -version 2>&1 | head -1)"

# Проверка подключения к Kafka
echo -n "Kafka test: "
timeout 5 kafka-broker-api-versions --bootstrap-server "$KAFKA_BOOTSTRAP" &>/dev/null \
  && echo "✅ OK" || echo "❌ FAIL"

# Проверка ClickHouse
echo -n "ClickHouse test: "
curl -sf -u "$CH_USER:$CH_PASS" "$CH_URL/?" -d 'SELECT 1' &>/dev/null \
  && echo "✅ OK" || echo "❌ FAIL"

5.3. Выполнение программы

Запуск в режиме systemd

# /etc/systemd/system/xengine.service
[Unit]
Description=X-Engine Stream Processor
After=Сеть.target kafka.service

[Service]
Type=simple
User=xengine
Group=xengine
ExecStart=/opt/xengine/bin/xengine start \
  --mode=stream \
  --config=/etc/xengine/config.yaml \
  --log-level=info
Restart=on-failure
RestartSec=10

# Важно: graceful shutdown за 30 с
TimeoutStopSec=30
KillSignal=SIGTERM

Команды управления:

sudo systemctl start xengine      # Запуск
sudo systemctl status xengine     # Состояние + последние логи
sudo systemctl reload xengine     # Перезагрузка конфига (без остановки)
sudo systemctl stop xengine       # Штатная остановка (ожидание завершения задач)
kill -SIGUSR2 $(pgrep xengine)   # Принудительный rotation логов

CLI-команды runtime (в REPL-режиме `xengine shell`)

Команда	Описание	Пример
`status`	Текущее состояние движка	`> status → {mode: stream, uptime: 2h13m, lag: 1.2s}`
`pause processing`	Приостановить обработку (буферизация продолжается)	`> pause processing`
`resume`	Возобновить	`> resume`
`stop --force`	Аварийное завершение (без сохранения состояния)	`> stop --force`
`config reload`	Перечитать `config.yaml` без перезапуска	`> config reload`

5.4. Сообщения оператору

Формат лога:
[2025-11-11T14:23:08.712Z][WARN][12345][main] XEN-2005: Rule 'fraud-detect-v3' took 1250ms (>1000ms threshold)

Код	Уровень	Текст	Причина	Действия
`XEN-2005`	`WARN`	`Rule '{name}' took {ms}ms (>1000ms threshold)`	Медленное правило	Проверить сложность условия, профилировать через `xengine profile --rule={name}`
`XEN-3011`	`ERROR`	`Failed to write batch to ClickHouse: Code: 241. DB::Exception: Memory limit exceeded`	Переполнение памяти в CH	Увеличить `max_memory_usage` в `users.xml`, уменьшить `batch.size`
`XEN-4000`	`FATAL`	`Required Kafka topic '{topic}' does not exist and auto.create.topics.enable=false`	Отсутствует топик	Создать топик вручную: `kafka-topics --create --topic events.raw --partitions 12 --replication-factor 3`

📌 Все сообщения логируются в journald и (при log.file.enabled=true) в /var/log/xengine/engine.log с ротацией через logrotate.

6. Чек-лист: «Готово ли Руководство оператора?»

Проверьте соответствие минимуму ГОСТ и практике:

№	Пункт	Выполнено? ✅/❌
1	Есть информационная часть (аннотация + содержание)
2	Все 4 обязательных раздела присутствуют
3	В разделе 1 указаны границы ответственности оператора
4	В разделе 2 — конкретные версии ПО/ОС, а не «рекомендованные»
5	В разделе 3 — точные команды запуска/останова + примеры
6	В разделе 3 — указаны коды возврата и их значения
7	В разделе 4 — все сообщения снабжены кодами (XEN-XXXX)
8	Для каждого сообщения ERROR/FATAL — алгоритм действий
9	Есть проверочные скрипты/команды диагностики
10	Есть приложения: примеры конфигов, схемы логов, таблица совместимости
11	Нет маркетинга, субъективных оценок, «воды»
12	Документ прошёл ревью с участием SRE/администратора

📥 Рекомендация: автоматизируйте валидацию через CI:

проверка наличия XEN-\d{4} в руководство.md;

проверка синтаксиса примеров bash через shellcheck;

валидация config.yaml по OpenAPI-схеме.

См. также

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

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