Писання документації Runbook англійською мовою: чіткі, готові до дії кроки
Вчимося писати документацію runbook англійською мовою, яка працює під тиском: імперативні кроки, точні дієслова, точки прийняття рішень і переписування до/ після для ясності.
Runbook — це покрокова інструкція щодо виконання операційного завдання або інциденту — перезапуску служби, відмови бази даних, очищення застряглої черги. Его читает встревоженный инженер в 3 часа утра, которому нужно действовать, а не интерпретировать. Це означає, що англійська мова повинна бути безжально чіткою: короткі імперативні дії, точні дієслова і чіткі моменти прийняття рішення. Цей посібник покаже вам, як це зробити.
Золоте правило: пишіть команди, а не описи
Кроки Runbook є ** інструкціями **, отже, скористайтеся ** імперативним настроєм ** (формою команди дієслова). Кожен крок починається з сильного дієслова дії.
| Descriptive (weak) | Imperative (strong) |
|---|---|
| “The service should be restarted." | "Restart the service." |
| "You will need to check the logs." | "Check the logs for OOMKilled." |
| "It is recommended to scale up." | "Scale the deployment to 5 replicas.” |
✅ “Спустити вузол. Закрити його. Зачекайте, поки підсистеми перепланують. Перевірити, чи рухався трафік перед продовженням.”
Кожен крок починається з дієслова, яке читач може робити. Ні “не слід”, ні “рекомендується”, ні пасивного голосу.
Використовуйте точні, однозначні дієслова
Оперативні дієслова мають конкретні значення. Вибір правильного запобігає помилкам.
| Verb | Means | Don’t confuse with |
|---|---|---|
| Restart | Stop then start | Reload (re-read config without stopping) |
| Drain | Move work off gracefully | Kill (terminate abruptly) |
| Failover | Switch to standby | Failback (switch back) |
| Roll back | Revert to previous version | Roll out (deploy forward) |
| Throttle | Slow down | Stop |
| Purge | Delete permanently | Clear (may be reversible) |
“Спорожніть чергу (не очистіть її — нам потрібні ці повідомлення). Потім перехід на інший сервер до репліки»
Попередження у дужках запобігає руйнівній помилці. Завжди позначати дієслова, які знищують дані.
Зробіть кожен крок перевіряним
Після виконання дії, повідомити користувачеві, як підтвердити, що вона спрацювала. Крок без перевірки залишає їх у впевненості.
- ** Перезапустити ** підсистеми
api: & # 160; … kubectl rollout перезапустити розгортання/ API & # 160; …- ** Перевірити ** всі підрозділи
Running: & # 160; … kubectl get pods - l app=api & # 160; … ✅ Очікувалося: всі підрозділиRunning, жоденCrashLoopBackOff.
Фраза « Очікувалося: », за якою слідує умова успіху, є надсиланням runbook. Читач точно знає, як виглядає “зроблено”.
Обробка точок рішення явно
Гілка реальних операцій: « якщо X, виконайте так; якщо ні, виконайте інакше ». Гілки пишуться як прості умовні речення, а не як захована проза.
** 3. Перевірити затримку реплікації: ** & # 160; … SELECT now () - pg_ last_ xact_ replay_ timestamp (); & # 160; …
- ** Якщо затримка менше 5 секунд ** → перейти до кроку 4.
- ** Якщо затримка перевищує 5 секунд ** → ** зупинити **. Позвоните в ДБА. Не перезапускай.
Форматування гілок як пунктів з жирним шрифтом робить їх сканування можливим під тиском. Використовуйте структуру « Якщо… тоді… » і використовуйте жирний шрифт для попередження про небезпечну гілку.
Написати попередження, які зупиняють людей
Загальні попередження ігноруються. Конкретні попередження з поясненням наслідків працюють.
| Weak warning | Strong warning |
|---|---|
| ”Be careful here." | "⚠️ This command drops the table. It is irreversible. Confirm you have a snapshot first." |
| "This is important." | "⚠️ Do not run this on the primary — only on a replica.” |
“⚠️ STOP. Наступний крок вилучає виробничі дані. Переконайтеся, що часовий штамп відповідає вікну інциденту ** перед** запуском його.”
Заявіть що відбувається і чому це важливо. Використовуйте ⚠️ і жирний шрифти обережно, щоб вони зберегли силу.
До і після: повне переписування
** До (абзацу, який ніхто не може прочитати о 3 годині ранку): **
«Коли черга застрягла, ви, ймовірно, повинні подивитися на споживача і, можливо, перезапустити його, якщо він виглядає нездоровим, і вам може знадобитися перевірити, чи обробляються повідомлення, і бути обережніми, щоб не втратити дані, тому що це було б погано»
** Після (сканування, імператив, перевірка): **
Runbook: Застрягла черга повідомлень
- Нет, не надо ** 1. Перевірка здоров’я споживача:** & # 160; … kubectl get pods - l app=consumer & # 160; …
- ** Якщо підрозділи
CrashLoopBackOff** → продовжити до кроку 2.- ** Якщо підрозділи мають значення
Running** → проблема є на нижньому рівні; перейдіть до розділу « Перевірки нижнього рівня ».- Нет, не надо 2. Перевірити журнали на наявність причини невдачі: & # 160; … kubectl logs - l app=consumer — tail=100 & # 160; …
- Нет, не надо ** 3. Перезапустити споживача:** & # 160; … kubectl rollout перезапустити розгортання/ споживача & # 160; … ✅ Очікувано: піддони повертаються до
Runningчерез 60 секунд.- Нет, не надо ⚠️ не очищати чергу. Повідомлення слід зберігати для повторного відтворення.
- Нет, не надо ** 4. Перевірити** повідомлення, що виводяться: & # 160; … rabbitmqctl list_ queues name повідомлення & # 160; … ✅ Очікувано: кількість
messagesзменшується.
Правила стилю для підручників
- ** Одна дія на крок. ** Не об’ єднуйте « перезапустити і перевірити і масштабувати » в один рядок.
- ** Число послідовних кроків; альтернативи пунктів. ** Порядок має значення у кроках; він не має значення між гілками.
- ** Вставляйте команди у блоки коду **, ніколи не вставляйте їх у речення, де проміжки неоднозначні.
- ** Записати умову успіху ** (« Очікувалося: ») після ризикованих кроків.
- ** Уникайте займенників. ** “Перезапустити” — перезапустити що? Кожен раз давати об’ єкту назву.
- **Уникайте слів, що відносяться до часу. ** “Нещодавно”, “новий”, “останнє виправлення” швидко гниють. Використовувати назви і версії.
Невідомі автори для невідомих авторів
- ** Імператив ≠ грубий. ** « Перезапустити службу » звучить як команда у багатьох мовах, але це правильна, нейтральна форма у технічній англійській.
- ** Уникайте слів « будь ласка » у кроках. ** Runbooks — це не запити, а інструкції. « Будь ласка, перезапустіть службу » послаблює їх.
- ** Використовуйте « should » лише для очікуваних результатів **, а не дій: « Под повинен повернутися до стану « Запускається » » (результат) проти « Перезапустити под » (дія).
- ** Виписуйте скорочення один раз. ** « Відновлення після аварії (FO) » вперше, потім « FO » — але тільки якщо ви використовуєте його неодноразово.
Ключевые вещи
- Напишіть кроки у ** імперативному настрої **, починаючи з сильного дієслова дії.
- Виберіть дієслова точно: ** drain ≠ purge **, ** roll back ≠ roll out **.
- Додати ** « Очікувалося: » ** умови успіху, щоб користувачі могли знати, коли крок було виконано успішно.
- Форматувати точки прийняття рішення як жирні ** якщо/ тоді ** гілки.
- Створюйте попередження конкретні та з послідовними заявами, з ⚠️ використовуються обережно.
Хороший план перетворює панічний 3-й ранку в спокійний контрольний список. Написати кожен крок так, ніби читач виснажений, наляканий, і читає його вперше — тому що одного дня, вони будуть.
Національні мови: мова не має офіційного статусу
Написання ефективних підручників не просто про перелік команд; це про створення чіткого, дієвого посібника для будь-кого - незалежно від їх рідної мови або рівня володіння англійською. Для розробників, які все ще будують свій професійний словник і розуміння спільних технічних фраз, прямота, часто знайдена в англійській мові, може бути особливо викликом. Важливо визнати, що точність не тільки про точність; це про передачу намірів недвозначно. Розгляньте недавній коментар перегляду коду, який ви отримали: « На цьому кроці бракує деталей — що * саме * ми перевіряємо? » Тут є незначний наслідок, що переглядачеві потрібна більш чітка мова, можливо, щось на зразок: « Перевірте, чи є стан програми « Виконання » за допомогою запиту на кінцеву точку стану за допомогою curl -s і перевірте відповідь JSON на поле « стан » зі значенням « Виконання ». » Бачите, як додавання додаткових деталей перетворює інструкцію з нечіткого на діюче?
Аналогічно, у розмовах Slack, пов’язаних з оновленнями Runbook, ключовим є уникнення надмірно скороченої мови або жаргону. Уявіть, що ви пишете опис запитів на звантаження: « Оновлений скрипт для міграції бази даних ». Цього недостатньо. Більш відшліфований підхід може бути: “Вреалізовано новий скрипт ( migrate_db.sh ) для виконання повної міграції схеми бази даних, забезпечення цілісності даних і мінімізації часу простою. Цей скрипт використовує psql з відповідними уповноваженнями і включає обробку помилок для запису будь-яких невдач. ” Розширений опис надає контекст - * чому * оновлення було необхідним, * як * воно реалізовано, і які заходи безпеки є на місці. Цей рівень деталізації не має на меті вразити когось; він має на меті зменшити неоднозначність для тих, хто виконає runbook пізніше.
Поширеною пасткою є використання надто складних структур речень просто для демонстрації авторитету або технічних знань. Стрімко до ясності, понад усе інше. Під час опису моменту прийняття рішення, замість « Якщо система не відповість, то продовжити з … » спробуйте щось на зразок: « Якщо система не відповість протягом 60 секунд, перейти до підтримки 2- го рівня за встановленими протоколами ». Ця зміна у формулюванні є незначною, але вона значно покращує зрозумілість і зменшує можливість неправильного тлумачення. Пам’ ятайте, ваша мета — допомогти іншим успішно виконати завдання, а не показати, як добре ви володієте англійською.
Нарешті, активне надання ресурсів може бути надзвичайно вигідним. Розгляньте можливість створення глосарію часто використовуваних технічних термінів — особливо тих, які мають декілька можливих перекладів — поряд з підручником з керування. Проста фраза, наприклад, «Посилайтеся на Додаток A для списку ключової термінології» забезпечує безпечну мережу і демонструє розуміння потенційних бар’єрів комунікації. Заохочуйте членів команди ставити питання і створюйте культуру, де пояснення цінується, а не сприймається як ознака слабкості.