Як написати Runbook Handoff для Multi-Region Failover в англійській мові

Передача runbook для перезавантаження декількох регіонів має працювати о 3 годині ранку, у часовому поясі, у якому ви спите, для інженера, який, можливо, ніколи не торкався цієї системи і не може задати вам прояснюючого питання. Це обмеження змінює те, як ви пишете англійською мовою: кожен крок повинен бути однозначним, кожне припущення має бути заявлено, а не натякнути, і кожне « очевидно » має бути вилучено, тому що нічого не очевидно для когось, хто виконує під тиском без автора в кімнаті.

Ключовий словник

** Відновлення після аварії ** — процес перемикання потоку або операцій з пошкодженої або погіршеної області на здорову, ідеально з мінімальними перешкодами. “Ця підручник по роботі включає перехід від регіону ЄС- Захід до регіону США- Схід у разі регіонального відключення.”

** Попередні умови ** — особливі умови, які мають бути виконані, перш ніж можна буде безпечно розпочати виконання runbook. “Передумови: підтвердити, що US- East повідомляє про стан здоров’ я на панелі інструментів, і що затримка реплікації менше 60 секунд перед продовженням.”

** Точка без повороту ** — крок у процедурі, після якого повернення назад стає значно важчим або неможливим, і який слід чітко позначити. “Крок 6 є точкою без повернення — як тільки DNS буде перенаправлено, відновлення потребує окремої процедури відновлення, а не просто повторення попередніх кроків в зворотному порядку.”

** Крок перевірки ** — явна перевірка, вставлена після дії, щоб підтвердити, що вона мала бажаний ефект перед переходом до наступного кроку.

• “Після підвищення рівня репліки, крок перевірки полягає у підтвердженні того, що трафік запису прибуває до східної частини США, перевіривши панель підрахунку з’ єднань.” *

** Шлях відновлення ** — задокументована альтернативна процедура для скасування відновлення, якщо щось не так під час виконання.

• “Якщо перевірка зазнає невдачі на кроці 4, скористайтеся шляхом відновлення з додатку B, а не продовжуйте виконання інших кроків відновлення.” *

Структурування документа Handoff

• “Ціль: Цей runbook не передає трафік з EU-West до US-East, коли EU-West погіршений або недоступний. Це повинно зайняти приблизно 15 хвилин для виконання»
• “Передумов (перевірити всі перед початком): Панель стану US-East показує зелений; затримка реплікації менше 60 секунд; ви маєте доступ до консолі керування DNS.”
• “Крок 1: Відкрийте консоль DNS на [посилання] і знайдіть запис для api.example.com. Не змінюйте нічого ще — цей крок є тільки для того, щоб підтвердити, що ви маєте доступ»
• Крок 2 (перевірка): Запустити curl -I https://api-useast.example.com/health і підтвердити, що ви бачите 200 OK перед переходом до кроку 3
• ”** Крок 6 (точці без повернення): ** Оновити запис DNS, щоб вказувати на балансувальник навантаження США-Схід IP. Розповсюдження зазвичай завершується протягом 5 хвилин, якщо врахувати наші параметри TTL

Писати для інженера, який не є там, щоб запитати вас

• «Якщо затримка реплікації перевищує 60 секунд на перевірці попередніх умов, зупиніть і ескалаціюйте до інженера бази даних на виклик, а не продовжуйте — не намагайтеся примусити підвищення»
• Якщо ви не впевнені, чи був крок успішно виконаний, розглядайте його як невдалий і використовуйте команду перевірки, а не припускайте, що він працював і йдіть далі
• «Ця книга запусків припускає, що вам вже надано роль «оператора відключення»; якщо ви не отримали її, запитайте її через [процес] перед продовженням, оскільки кроки 5 і далі зазнають невдачі без неї»

Професійні поради

• ** Зазначте попередні умови у вигляді контрольного списку, а не прози. ** Хтось під тиском має швидко сканувати і підтверджувати кожен пункт, а не аналізувати абзац, щоб витягнути те, що слід перевірити.
• ** Позначте точку, з якої немає повернення, у власному кроці з назвою. ** Назва цього кроку позбавляє вас від здогадок щодо того, які дії все ще безпечно повернути, а які — ні.
• ** Додати крок перевірки до кожної дії, яка змінює стан системи. ** Крок без способу підтвердження успіху залишає користувача у стані здогадки, чи продовжувати, що є абсолютно неправильним під час відключення.
• ** Записувати тригери ескалації як явні if/ then- речення. ** « Якщо X, тоді ескалація до Y » вилучає виклик судження від когось, хто може не мати контексту, щоб зробити це впевнено.

Практичні вправи

1. Написати контрольний список « Попередніх умов » з трьох пунктів для гіпотетичного каталогу виконання відключення.
2. Написати один крок перевірки, який слідує за дією зміни стану, включаючи точну команду або перевірку, яку слід виконати.
3. Напишіть речення ескалації у формі « Якщо [умова], то [дія] » для кроку, який може закінчитися невдачею.

Зв’язані ресурси

• Як пояснити затримку поширення DNS англійською мовою
• Як написати технічний запис рішення англійською мовою

Складні мови: мова опису і мова опису критичних ситуацій

Основні принципи створення ефективної передачі Runbook — чіткі інструкції, оновлений стан і чітко визначені шляхи ескалації — залишаються незмінними незалежно від вашої рідної мови. Однак, при повідомленні складних технічних процедур колегам, які можуть розвивати свою професійну англійську, тонкий зсув у словниковому запасі і фразування може значно поліпшити розуміння і зменшити неоднозначність. Розгляньте вплив неформальної мови або надмірно спрощених пояснень; хоча вони призначені для доступності, їм часто бракує точності, необхідної під час ситуації високого тиску, наприклад, багаторегіонального відключення.

Розглянемо деякі спільні області, де важливий ретельний вибір слів. Замість того, щоб сказати « Я зробив це », що є неясним, спробуйте « Я розпочав процес [конкретною дією], щоб забезпечити [бажаний результат] ». Це надає контекст і пояснює * чому * ви зробили цей крок. Аналогічно, уникай фраз на кшталт «просто дай мені знати» — це означає пасивне очікування. Краще було б вказати: « Будь ласка, стежте за станом [метрики] кожні п’ ять хвилин і негайно повідомляйте мене, якщо він відхиляється від очікуваного діапазону ». Цей варіант є більш директивним, професійним і не залишає місця для інтерпретації ваших очікувань.

Крім того, зверніть увагу на опис станів. Замість того, щоб сказати « це не працює », точнішим і корисним описом буде « Служба має підвищений рівень помилок (поки що 15%), що впливає на [особливі функціональні можливості], як повідомляється на панелі керування ». Числа мають велике значення; коли це можливо, вкажіть кількісну оцінку проблеми. Під час опису кроків, використовуйте дієслова з наказовим відмінком — « Розгорнути нові налаштування », « Перевірити з’ єднання з базою даних », « Відновити зміни, якщо це необхідно ». Уникайте двозначних фраз на зразок « подбати про це » або « подивитися на це ».

Нарешті, пам’ ятайте, що добре написаний опис PR для процесу відключення також має бути вкладений у форму * запит * на дію. Розгляньте цей приклад: « Будь ласка, перегляньте і затвердіть запропоновану процедуру відновлення, описану у цьому документі, перед початком операції відновлення. Потрібне ваше підтвердження для продовження активації вторинної області. » Це демонструє відповідальність і забезпечує, що інженер, який знаходиться на черзі, розуміє свою роль у процесі. Спрямування уваги на ясну, точну мову у всій вашій документації не лише принесе користь користувачам, для яких англійська мова не є рідною, але також покращить спілкування для всіх, хто бере участь у цьому процесі.

---