Эксплуатационная инструкция: симптом, действие, откат и проверка

Проблема инструкции обнаруживается в первый же сбой: читатель знает, что сервис нездоров, но не понимает, какой командой начать и как не усугубить ситуацию. Цена расплывчатого текста — параллельные ручные действия, потеря исходных метрик и откат без проверки данных.

Причина — писать статью как последовательность уверенных советов. В эксплуатации важнее не количество команд, а граница каждой команды: какое условие должно быть истинным, какой результат ожидается и когда нужно остановиться. Reader-facing текст должен позволить сверить вход, выполнить один шаг и увидеть измеримый выход.

Карточка операции — минимальная единица

Полезная инструкция начинается с симптома и scope: например, «5xx выше 5% на POST /payments в одном регионе». Затем идут precondition, действие, rollback и verification. Эти поля не формальность. Без scope оператор может отключить здоровый трафик; без precondition — выполнить команду на неправильной версии; без verification — принять завершение команды за восстановление.

Порядок должен отражать риск, а не удобство автора документа. Сначала сохранить наблюдаемый факт, потом ограничить влияние, затем изменить один рычаг. После действия нужен интервал наблюдения и критерий возврата. Если операция необратима, инструкция должна прямо сказать, что её нельзя запускать без отдельного разрешения и резервного пути.

Глаголы задают риск

Рекомендации вроде «проверьте», «убедитесь» и «при необходимости» слишком широки, если рядом нет объекта. RFC 2119 полезен как дисциплина модальности: MUST можно применять к обязательной precondition, SHOULD — к шагу с допустимым исключением, а MAY — к необязательной диагностике. В русском тексте это можно перевести обычными словами, сохранив однозначность.

Каждый command block должен иметь входы и ожидаемый результат. Если команда меняет состояние, рядом укажите право, namespace и способ увидеть diff. Не вставляйте секрет в пример и не предполагайте, что читатель знает локальные alias. Хорошая краткость убирает лишние слова, но не убирает условия безопасности.

Runnable-пример: проверить карточку runbook

Функция принимает объект с шестью полями и проверяет, что каждое достаточно содержательно, rollback назван явно, а verification ссылается на наблюдаемый сигнал. Это учебная проверка структуры документа, не оценка литературного стиля и не разрешение выполнить команду. Вход ниже показывает минимальный принятый набор и отказ без измеримой проверки.

import { validateRunbookCard } from './upgrade-2027-12.mjs';

const card = validateRunbookCard({
  symptom: '5xx выше 5 процентов на POST /payments',
  scope: 'region eu-west, release 42, 10 percent traffic',
  precondition: 'есть доступ к flag и сохранён dashboard за 15 минут',
  action: 'отключить flag payments-v2 для 10 процентов трафика',
  rollback: 'вернуть flag payments-v2 после проверки результата',
  verification: 'проверить error rate и p95 в течение 10 минут',
});

console.log(card.ok, card.order.join(' -> '));
// true symptom -> scope -> precondition -> action -> rollback -> verification

Порядок редакторской проверки инструкции

1. В первых двух абзацах назовите симптом и цену ошибки. Reader должен понять, для какой ситуации текст предназначен.
2. Сделайте scope измеримым: endpoint, регион, версия, доля трафика и временное окно.
3. Перед каждой опасной командой поставьте precondition и ожидаемый output. Если output не наблюдаем, шаг нельзя считать проверенным.
4. Разделите один шаг изменения и rollback. Для rollback укажите условие, а не только команду возврата.
5. Добавьте таблицу решений для соседних симптомов, чтобы reader не применил одинаковое действие к 500, timeout и 409.
6. Запустите учебный пример с валидной и неполной карточкой, затем перечитайте текст на мобильной ширине и уберите длинные строки.

Технический текст не заменяет разрешение

Даже подробная инструкция не даёт права менять production. Доступ, approval и окно операции должны жить в локальном процессе, а статья должна честно указать, какие precondition ей неизвестны. Если шаг может удалить данные или нарушить доступность, reader должен увидеть остановку до команды, а не бодрый призыв продолжать.

Не стоит добавлять в runbook вымышленные метрики и имена сервисов только для гладкого чтения. Лучше оставить placeholder с точным описанием входа, чем заставить оператора повторить чужой пример. Учебный пример должен быть маркирован как учебный и не содержать секретов, настоящих hostnames или команд с необратимым эффектом.

Ограничения и следующий шаг

Проверка карточки не знает прав, shell, облака, backup, lock и реальных порогов. NIST SP 800-61 задаёт общий цикл обращения с инцидентом, но ваша инструкция всё равно должна назвать локальные сигналы и способ остановки. RFC 2119 помогает выбрать модальность, но не тестирует исполнимость команды.

Следующий шаг — взять один существующий alert и переписать его в шесть полей, затем прогнать на staging с безопасным флагом и настоящей проверкой метрики. Если reader не может назвать ожидаемый output любого шага, вернитесь к precondition и добавьте наблюдаемый критерий.

Проверяемые источники

• NIST SP 800-61 Revision 2 — Computer Security Incident Handling Guide — NIST, revision 2, май 2012 года, Special Publication 800-61. Применение: Даёт дисциплину подготовки, обнаружения, анализа, containment, восстановления и работы после инцидента для структуры эксплуатационной инструкции. Граница: Не знает ваших команд, прав доступа, сервисных зависимостей и порогов остановки.
• RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels — IETF, март 1997 года, RFC 2119. Применение: Фиксирует различие между обязательным, рекомендуемым и необязательным действием, чтобы инструкция не прятала приоритет в тоне. Граница: Не является руководством по эксплуатации, не проверяет команду и не даёт разрешение менять production.