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

Чисто написаний звіт про помилку — це одна з найцінніших речей, які ви можете створити як розробник, інженер з контролю якості або технічний користувач. Добре написаний звіт про помилку заощаджує час на зневадження, скорочує час, який йде на перевірку, і збільшує шанси на швидке виправлення проблеми. Погано написаний звіт про ваду марнує час всіх, і може призвести до закриття проблеми з помилкою « неможливо відтворити ». У цьому підручнику описано, як написати ефективний звіт про ваду технічною англійською мовою.

---

Основні компоненти звіту про помилку

Кожне гарне повідомлення про помилку містить ті самі основні елементи. Подумайте про них як про рецепт — пропустіть один інгредієнт, і результат постраждає.

Заголовок

Ясний, конкретний заголовок, який описує проблему, а не симптом. Вона повинна відповідати на питання “що ламається” і “де”

Неправильний заголовок:

“Вход не работает”

Краща назва:

• « Спроба входу зазнала невдачі з помилкою 500, якщо електронна пошта містить знак плюс (+) » *

Хороший заголовок дає змогу розробнику зрозуміти обсяг проблеми перед відкриттям звіту.

Середовище

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

“Околіця: - Переглядач: Chrome 124.0 на macOS 14.3

• • Версія API: v2. 4. 1 *
• • Тип облікового запису: Безкоштовний рівень * *- Регіон: ЄС (eu- west- 1)» *

Для помилок сервера, включіть версію сервера, ОС, відповідні прапорці налаштування і версію бази даних.

3-й. Кроки до відтворення

Пронумерований список точних кроків, які потрібно виконати для виклику вади. Бути точним — використовувати точні значення, а не наближені.

Погане:

• “Перейти до панелі інструментів і спробувати експортувати.” *

Краще:

• “Кроки для відтворення: *
• 1. Ввійдіть за допомогою облікового запису безкоштовного рівня.*
• 2. Перейдіть до пункту Панель приладів > Звіти.*
• 3. Натисніть « Експортувати як CSV ».*
• 4. У інструменті вибору діапазону дат оберіть діапазон, більший за 90 днів.*
• 5. «Знижку» (нім

Людина, яка виправляє ваду, повинна знати, як виконати ці дії і побачити ту ж саму проблему, не запитуючи вас про це.

4. Очікувана поведінка

Описуйте, що має статися — не те, що ви бажаєте, щоб сталося, а те, що є документованою або запланованою поведінкою.

• “Очевидна поведінка: Звантаження файла CSV, у якому містяться дані звіту за вибраним діапазоном дат, має розпочатися.” *

5. Фактична поведінка

Опишіть, що насправді відбувається. Включити точні повідомлення про помилку, коди помилок і відповідний вивід журналу.

• “Справжня поведінка: кнопка звантаження перестає відповідати. Немає звантаження файлів. У консолі переглядача буде показано: *
• Error: Request failed with status code 504 (Gateway Timeout) “*

6-й. Серйозність і пріоритет

** Серйозність ** описує вплив вади на систему:

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

** Пріоритет ** описує, наскільки терміново слід виправити помилку — це бізнес- рішення, відмінне від ступеня тяжкості.

• « Серйозність: Висока (основні функції експорту не працюють для всіх користувачів з діапазонами дат більше 90 днів) » *

---

До і після: повний приклад

Погана звітність (англ. Poor Reporting)

• “Експорт пошкоджено. Я намагався експортувати звіт, але це не спрацювало. Будь ласка, виправте».*

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

Good Bug Report (англійською)

** Заголовок: ** Експорт до CSV зазнає невдачі з таймом очікування 504 для діапазонів дат, що перевищують 90 днів

• Нет, не надо ** Середовище: **
• Версія програми: 3.7.2
• Браузер: Firefox 125 на Windows 11
• Тип рахунка: Бізнес- план
• Нет, не надо Кроки для відтворення:

1. Європа Ввійти як користувач з бізнес- планом. 2-й. Перейдіть до пункту Звіти > Нетиповий звіт. 3-й. Встановити діапазон дат до 1 січня 2025 — 31 травня 2025 (151 день). 4-й. Натисніть « Експортувати як CSV »

• Нет, не надо ** Очікувана поведінка: ** Файл CSV звантажується протягом 30 секунд.
• Нет, не надо ** Справжня поведінка: ** На сторінці приблизно 60 секунд буде показано стрілочку завантаження, а потім буде показано повідомлення « Сталася помилка. Будь ласка, спробуйте ще раз.» На вкладці мережі показано відповідь 504 від /api/reports/export.
• Нет, не надо ** Серйозність: ** Висока — можливість експорту є основним способом, за допомогою якого користувачі бізнес- плану витягують дані для створення звітів.
• Нет, не надо ** Додаткові зауваження: ** Ця проблема не виникає у діапазонах дат 89 днів або менше. Перевірено на Chrome 124 з тим же результатом.

---

Корисні фрази для звітів про вади

• “Проблема виникає постійно, коли…”
• • « Мені не вдалося відтворити проблему у середовищі тестування. » *
• • « Показано повідомлення про помилку: [точний текст] » *
• • « Ця поведінка не відповідає документації, яка говорить про те, що… » *
• • « Обхідним рішенням є…, але це не прийнято як постійне рішення. » *
• • « Я долучив запис екрана, що демонструє проблему. » *
• “Проблема вперше з’явилася після розгортання версії 3.7.0.”

---

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

Національні мови: мова рідного народу, мова ненаціональних меншин

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

Частою проблемою є використання надто буквальних перекладів. Наприклад, безпосередній переклад «Це не працює» на «Це не працює» може бути технічно коректним, але не має професійного тону, очікуваного в звіті про помилку. Замість цього спробуйте написати щось на зразок « Програма не змогла запустити процес розпізнавання користувача ». Таким чином використовується більш описова мова і уникається неоднозначності. Аналогічно, фрази типу «Я знайшов помилку» є занадто неформальними для формального звіту; «Я виявив проблему, що впливає на…» є набагато більш відповідним. Пам’ ятайте, ваша мета - не просто * сказати * комусь, що є проблема, але надати їм інформацію, яка їм потрібна, щоб * виправити * її ефективно. Зверніть увагу на дієслова - “причина”, “тригер” і “вплив” часто краще за простіші терміни, такі як “зробити” або “створити”, коли описується ефект помилки.

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

Розглянемо повідомлення Slack від Сари до її керівника команди Марка після того, як вона зіткнулася з проблемою. Замість того, щоб вводити “Bug! Він не завантажується,” вона пише, “Я стикаюся з періодичними проблемами з завантаженням каталогу продуктів в середовищі стажування. Я підтвердив, що мій браузер є актуальним (Chrome v120) і очистив кеш. У консолі буде показано повідомлення про помилку: « TypeError: Не вдалося прочитати властивості undefined (читання « name »). ». Я можу відтворити це послідовно, коли переходжу до сторінок продуктів з великою кількістю пов’ язаних оглядів. Я долучив до цього вивід журналу консолі для вашого перегляду. » Зауважте різницю — цей вивід є докладним, конкретним і демонструє активний підхід. Цей рівень ясності значно скорочує час, витрачений на переслідування інформації і дозволяє Марку швидко оцінити проблему і ефективно розподілити ресурси.