Як писати технічні Runbooks англійською

Книга-посібник є тільки на стільки, наскільки вона чітка. У випадку високого тиску інженер, який слідує погано написаному посібнику — або гірше, написаному неоднозначною англійською — може зробити все гірше, а не краще. У цій статті описано словниковий запас для вмісту runbook, шаблони написання англійською мовою, які роблять runbook однозначним і дійсним, а також найпоширеніші помилки, які призводять до невдачі runbook на практиці.

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

Книга походів Документований набір процедур для роботи, розв’ язання проблем або відновлення системи. Runbooks написані заздалегідь, щоб кожен в команді - включаючи когось, хто не знайомий з системою - міг слідувати за ними під тиском.

• Приклад: « Існує підручник для відновлення роботи бази даних у Confluence — скористайтеся ним крок за кроком, а не імпровізуйте ». *

Передусловия Вимоги, які мають бути виконані перед початком процедури. Перевірка попередніх умов запобігає виконанню кроків, які зазнають невдачі або спричиняють шкоду, оскільки середовище не знаходиться у очікуваному стані.

• Приклад: « Попередні умови: переконайтеся, що база даних репліки повністю синхронізована перед початком процедури відключення. » *

** Очікувані результати ** Якою має бути система після кожного великого кроку — використовується для перевірки успішного виконання кроку перед продовженням. Без очікуваних результатів, оператори не можуть сказати, чи крок працював, чи беззвучно зазнав невдачі.

• Приклад: « Очікуваний результат: кінцева точка перевірки стану повертає HTTP 200 протягом 30 секунд після перезапуску. » *

** Кроки відновлення ** Процедури скасування змін, внесених під час операції, якщо щось пішло не так. Runbook без кроків відновлення залишає інженерів в пастці, якщо основна процедура зазнає невдачі.

• Приклад: « Якщо розгортання зазнає невдачі після кроку 3, виконайте дії щодо відновлення, описаних у розділі 4, щоб відновити попередню версію. » *

Порог важкості Визначений критерій, який визначає, чи буде інциденту надано ступінь ескалації, який рівень відповіді він вимагає, або який підручник для виконання використовувати.

• Приклад: “Якщо частота помилок перевищує 5% протягом більше 2 хвилин, цей інцидент перевищує поріг серйозності для P1 і слід повідомити про це на виклик.” *

Процедура ескалації Документовані кроки для передачі інциденту на підтримку вищого рівня — старшому інженеру, інженерному менеджеру або зовнішньому постачальнику.

• Приклад: « Якщо ви не зможете розв’ язати проблему протягом 30 хвилин, виконайте процедуру ескалації: повідомте про це керівника з обслуговування за викликом і відкрийте квиток у постачальника бази даних. » *

** Дерево рішень ** Структура гілок у runbook, яка веде оператора до різних процедур на основі того, що він спостерігає. Необхідно для розв’ язання проблем у розділах, де правильна дія залежить від того, що робить система.

• Приклад: « Дерево рішень у розділі 2 покаже вам правильну процедуру, залежно від того, чи є помилка перевищенням часу очікування або помилкою розпізнавання. » *

** Блок- схема розв’ язання проблем ** Візуальне або структуроване представлення дерева рішень, яке показує шляхи розгалуження для різних діагностичних результатів. Часто представлений як пронумерований список з умовними гілками.

• Приклад: « Слідкуйте за блок- схемою усунення неполадок — якщо перевірка стану не вдалася, перейдіть до кроку 4a; якщо вона пройшла успішно, але затримка є високою, перейдіть до кроку 4b. » *

Фрази і фразеологізми

Наказні настрої Типовий стиль написання кроків runbook — використовувати дієслова команд безпосередньо. Не “тобі слід перевірити”, а “перевірити” Приклад: «Перезапустити службу. Перевірте, чи успішно запускається програма, перевіривши кінцеву точку стану. Якщо він не запускається, зіберіть журнали перед продовженням.»

** Умовні інструкції (« Якщо X, то Y ») ** Використовується для прийняття рішень у розв’ язанні проблем з runbooks.

• Приклад: « Якщо підсистема не запускається протягом 60 секунд, перевірте журнал подій за допомогою kubectl describe pod. Якщо ви бачите стан OOMKilled, збільште обмеження пам’яті і перерозгорніть.”*

** « Перевірити, що… » / « Підтвердити, що… » ** Використовується для введення очікуваних перевірок результатів після кроку.

• Приклад: « Перевірити, чи кількість з’ єднань з базою даних не впаде нижче 50 протягом 2 хвилин після вмикання автоматичного вимкнення ». *

“Не продовжувати доки…” Сильна мова, яку використовують, коли крок не слід пропускати навіть під час надмірного часу.

• Приклад: « Не продовжувати доки не буде підтверджено завершення резервування. Перевірте стан резервного копіювання в консолі адміністрування.”*

** « Зауваження: » і « Попередження: » ** Мітки підказок для контекстної інформації і критичних попереджень відповідно.

• Приклад: « Попередження: цей крок призведе до приблизно 30- секундного переривання роботи у вражених областях. Підтвердити з інциденту ведучий перед виконанням.”*

Практичні рекомендації

1. «Передусім: вікно обслуговування активне, балансувальник навантаження було оновлено, щоб виключити цей вузол, і ви маєте доступ SSH до вузла.»
2. Якщо служба не запускається, не переходьте до кроку 5 — збирайте журнали служб і ескалацію за допомогою процедури ескалації в Додатку A
3. “Очакуваний результат: глибина черги впаде нижче 100 повідомлень протягом 5 хвилин. Якщо це не так, то споживач може не обробляти правильно — слідуйте дереву рішень в розділі 3
4. “Ця книга описує перезавантаження бази даних. Для відключення рівня програми, зверніться до Runbook відключення програми.”
5. “Попередження: виконання кроків відновлення призведе до відкидання всіх записів, зроблених після останнього зніму. Перед продовженням роботи підтвердіть це з власником даних»

Необхідно уникати помилок

Писаю пассивним голосом Пасивний голос у Runbooks створює неоднозначність щодо того, хто що робить.

• Замість: « Службу слід перезапустити. » *
• Промовте: « Перезапустити службу за допомогою: systemctl restart app-service » *

** Відсутні очікувані результати після кроків ** Без очікуваних результатів, оператор не може сказати, чи працював крок. Вони можуть продовжувати працювати на пошкодженій системі, що зробить все ще гіршим.

• Замість: “3. Перезапустити репліку бази даних.”* Скажи: “3. Перезапустити копію бази даних. Очікуваний результат: репліка з’ єднається з головною через 90 секунд. Перевірити затримку реплікації за допомогою: SHOW SLAVE STATUS\G ”

** Без включення кроків відновлення ** Runbooks, які описують тільки «щасливий шлях» є неповними. Завжди запитуйте: що ми робимо, якщо крок N зазнає невдачі?

• Замість: опису лише кроків розгортання *
• Додати: « Відновлення: якщо розгортання зазнає невдачі на кроці 4 або пізніше, виконати скрипт відновлення на кроці /scripts/rollback.sh з тегом попередньої версії як аргументом. » *

Summary

Написання ефективних підручників англійською мовою вимагає певного словникового запасу (передумови, очікувані результати, процедури ескалації, дерева рішень) і певного стилю написання — імперативного настрою, умовного розгалуження, явних кроків перевірки. Runbooks є критичним документом безпеки: коли відбувається інцидент, неоднозначна мова коштує часу і призводить до помилок. Інвестиції в чітке, точне написання англійської мови виплачуються кожного разу, коли ваша команда стикається з інцидентом — саме тоді, коли вам потрібна ідеальна мова.

Розмовляють мовою рунґа

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

Однією з найчастіших проблем є використання надто складних структур речень. Інструкції Runbook повинні бути прямими і короткими. Замість того, щоб сказати « Перед наступною операцією вам обов’ язково слід перевірити цілісність бази даних », скористайтеся простішим підходом: « Перед продовженням, * перевірте * цілісність бази даних ». У початковій формулюванні використано надмірно формальну мову (« це обов’ язково »), яка може здатися занадто громіздкою і заплутаною. Аналогічно, уникайте надто складних описів. Сфокусуйтеся на тому, що потрібно зробити, а не на тому, як це слід зробити — саме тут використовуються докладні діаграми і підтримуюча документація. Задумайтесь, як би колега міг швидко сканувати інструкції; ясність переважає над вичерпними деталями.

Іншою областю, на якій варто зосередитися, є послідовне використання активного голосу. Пасивні конструкції, такі як « Сервер було перезапуску за допомогою скрипту автоматизації », є поширеними, але вони можуть затьмарити відповідальність і зробити процес менш зрозумілим. Перемкнути на « Скрипт автоматизації перезавантажив сервер ». Цей безпосередній підхід негайно визначає, хто або що виконало дію. Крім того, зверніть увагу на умовне вираження. Замість « Якщо код помилки 500, * тоді * вам слід … » спробуйте « Якщо код помилки 500, * виконайте наступні дії * … ». Останнє звучить більш авторитетно і дає чіткий сигнал, що йдуть подальші інструкції.

Нарешті, під час написання описів PR для runbooks, пам’ ятайте, щоб чітко сформулювати * чому *, а не лише * що *. Хороший PR-опис може звучати так: «Це оновлення реалізує автоматичне масштабування веб-серверів під час періодів пікового навантаження на основі метрик, зібраних Prometheus. Це забезпечить оптимальну продуктивність і зменшить затримку. » Уникайте простого вказівки « Оновлена логіка масштабування ». Доданий контекст пояснює мету і вплив зміни, що є важливим для переглядачів, які не мають глибокої інформації про архітектуру, за якою вона створена. Пам’ятайте, добре написаний підручник не тільки про кроки; це про будівництво спільного розуміння в межах вашої команди.