Руководство оператора по ГОСТ 19.505-79
ERD и словарь сущностей — Entity Relationship, нормализация, SQL. Карта — о разделе.
Руководство оператора
Основано на ГОСТ 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, тип файловой системы)
- CPU (ядра, архитектура:
- Требования к программному обеспечению:
- ОС (в т.ч. дистрибутивы 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, схемы валидации |
| Запуск | Интерактивный/фоновый, CLI, systemd, контейнер | см. блок "Запуск" ниже |
| Управление | — Команды 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".
Примеры запуска:
xengine start --mode=batch --config=/etc/xengine.yaml
sudo systemctl start xengine
docker run -d --name xengine -v /etc/xengine:/config xengine:2.1 --config=/config/xengine.yaml
podman run -d --replace xengine xengine:2.1
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 |
Типовые действия оператора из колонки "Действия":
chmod 640 /etc/xengine.yaml
pg_isready -h db -p 5432
xengine start --mode=batch --config=/etc/xengine.yaml
✅ Обязательно укажите: формат лог-сообщения (
[TIMESTAMP][LEVEL][PID] CODE: message), пути к логам и фильтрацию:
journalctl -u xengine -f
grep -E 'XEN-[34].*' /var/log/xengine/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)
- Kafka 3.5+ (
- Права: пользователь
xengine, группаxengine;CAP_NET_BIND_SERVICE(для порта 8080)
Проверка окружения (скрипт /opt/xengine/bin/env-check.sh)
Код ITЗагрузка примера кода…
5.3. Выполнение программы
Запуск в режиме systemd
Код ITЗагрузка примера кода…
Команды управления:
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-схеме.
Дополнение — операторские сценарии, которые стоит раскрыть
Базовый набор рабочих сценариев
- старт смены и проверка готовности системы;
- выполнение ключевой операции с ожидаемым результатом;
- завершение смены и контроль передачи данных;
- действия при типовой ошибке интерфейса.
Улучшение обучаемости
Добавьте блок "5-минутный маршрут новичка" — что читать первым, какую операцию выполнить для тренировки и по каким признакам понять, что результат корректный.