Як писати книгу англійською мовою

Runbook, написаний для людини, яка вже розуміє систему, є безкорисливим для виснаженого інженера на черзі о 3 годині ранку, який цього не робить — цей посібник охоплює структуру, яка робить runbook насправді використовувати під тиском.

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

** Умова спуску ** — певний, спостережуваний сигнал, який означає, що цей підручник з керування буде застосовано, наприклад, певне попередження або перевищення порогу метрики, зазначений достатньо точно, щоб хтось міг підтвердити, що він знаходиться у правильному підручнику з керування, перш ніж виконувати дію. “Умова спуску повинна бути конкретною — «високої затримки» недостатньо, але «побілювання про затримку p99 для служби замовлення триває більше п’яти хвилин» говорить інженеру-покликаному, коли саме застосовується цей підручник.»

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

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

• “Додати крок перевірки після перезапуску — перевірити, чи дійсно знизилася кількість помилок на панелі інструментів, а не лише те, чи команда перезапуску завершилася успішно, оскільки перезапуск може бути успішним, якщо справжня проблема залишається.” *

** Шлях ескалації ** — явний наступний крок і контакт, якщо виправлення runbook не вирішить проблему, включаючи кого сторінювати і через який час, щоб інженер на виклику не залишався імпровізувати, коли документоване виправлення не працює. “У Runbook потрібна категорія ескалації — якщо стандартне усунення не усуває попередження протягом двадцяти хвилин, то він повинен точно вказати, кому слід перейти на наступну сторінку, замість того, щоб залишати інженера на черзі, щоб той зрозумів, кому належить ця система.”

Звичайні фрази

• «Що таке тригерна умова — як ми знаємо, що ця книга дійсно застосовується?»
• Чи є покрокова реабілітація достатньо конкретною, щоб слідувати без додаткового контексту?
• Чи включає це крок перевірки, або ж це просто припускає, що виправлення працювало?»
• Який шлях ескалації, якщо ліквідація не вирішить її вчасно?
• Чи був цей Runbook насправді перевірений кимось, хто не знайомий з системою?»

Приклади висловлювань

Визначення умови тригера:

• “Станція спуску: попередження OrderQueueBacklog, яке вказує на те, що у черзі замовлень більше 10 000 необроблених повідомлень, які не оброблялися протягом п’ яти хвилин. Підтвердіть це конкретне попередження перед продовженням — загальне попередження про глибину черги є іншою, менш невідкладною ситуацією.”*

Записувати окремі кроки відновлення:

• “Крок 1: SSH на робочому вузлі з ssh worker-prod-3. Крок 2: Виконати sudo systemctl restart order-worker. Крок 3: Підтвердіть, що служба активна за допомогою systemctl status order-worker — ви повинні побачити ‘активний (працює)’ протягом 30 секунд.”*

Запис шляху ескалації: “Якщо глибина черги не почала зменшуватися протягом 15 хвилин після перезапуску, перейдіть до платформи за запитом за допомогою PagerDuty, а не продовжуйте повторювати ті ж самі спроби відновлення — постійне відставання після чистого перезапуску зазвичай вказує на глибшу проблему.”

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

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

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

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

Науковий ступінь бакалавра: англійська мова, міжнародні відносини

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

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

Іншою областю, на якій варто зосередитися, є ясність щодо власності і підзвітності. Стандартною фразою, яку використовують під час перегляду коду, наприклад, є « Чи можете ви пояснити логіку, яка стоїть за цим підходом? » Це не є обвинуваченням; це ввічлива пропозиція подальшого пояснення, що демонструє бажання зрозуміти * чому * перед тим, як запропонувати альтернативу. У Slack повідомленнях щодо ескалації проблем, використовуючи такі фрази, як «Ми вимагаємо негайної уваги до цього критичного інциденту» - а не «Це пошкоджено!» - негайно встановлює терміни і важливість. Під час створення описів PR для оновлень runbook, змінюйте рамки з сильними дієсловами і кількісними результатами: « Переглянутий протокол ескалації, щоб скоротити середній час розв’ язання на 15%. »

Нарешті, пам’ятайте, що точність у термінології є життєво важливою. Уникайте колоквіалізмів або жаргонів, які не можуть бути зрозумілими для всіх. Якщо термін має декілька інтерпретацій, визначте його явно у самому runbook — наприклад, « У цьому контексті, « затримка » відноситься до … » Це демонструє увагу до деталей і зменшує неоднозначність, що є надзвичайно важливим при роботі з потенційно складними операційними ситуаціями. Хорошим прикладом цього на практиці буде відповідь на коментар перегляду коду: “Дякую за підсвічування цієї потенційної проблеми; Я включив вашу пропозицію щодо логіки обробки помилок для поліпшення надійності”