Як описати Bug чітко англійською мовою
Ясно описати ваду англійською мовою: очікувана поведінка у порівнянні зі справжньою, кроки відтворення, подробиці щодо середовища і точні дієслова, за допомогою яких можна негайно виконати дії, вказані у звіті.
Найбільш корисною навичкою у будь- якому звіті про помилку є такий чіткий опис проблеми, що інший інженер зможе відтворити її без запитання. Більшість звітів про вади не вдалося завершити. Цей посібник надає вам просту структуру і точну англійську, яка перетворює * « це не працює » * на звіт, який хтось може виправити сьогодні.
Золоте правило: очікуваний vs. фактичний
Кожен чіткий опис вади порівнює дві речі:
- То, чого ти очікував.
- Що насправді сталося замість цього.
- “Я очікував, що форма надасть повідомлення про успіх. Замість цього, сторінка перезавантажилася, а форма була порожня, без показаної помилки.”*
Якщо ви описуєте тільки одну сторону, читач повинен вгадати іншу. Завжди вказуйте обидва.
Проста конструкція
- ** Резюме ** — одне речення.
- ** Кроки для відтворення ** — пронумеровані.
- ** Очікуваний результат. **
- ** Фактичний результат. **
- ** Середовище ** — переглядач, ОС, версія, тип облікового запису.
- ** Доказ ** — знімок екрана, журнал, повідомлення про помилку.
** Резюме: ** Вивантаження файла PDF розміром більше 5 МБ зазнає невдалої спроби. ** Кроки: ** 1. Перейти до розділу Документи. 2. Натисніть кнопку Вивантажити. 3. Виберіть PDF розміром 6 МБ. ** Очікувалося: ** Файл буде вивантажено і з’ явиться у списку. ** Фактична: ** Смужка поступу досягає 100%, після чого нічого не відбувається. Не показано жодного файла, не показано жодної помилки. ** Середовище: ** Chrome 124, macOS, обліковий запис Pro.
Використовується для опису поведінки
Неясні дієслова всіх сповільнюють. Використовувати точні:
| Vague | Precise |
|---|---|
| ”It breaks." | "It throws a 500 error." |
| "It’s weird." | "The list shows duplicate entries." |
| "It freezes." | "The UI becomes unresponsive for about ten seconds." |
| "Nothing happens." | "The button click has no visible effect and logs no request.” |
“Запит зависає на 30 секунд, потім закінчується час з помилкою 504.”
Описуючи частоту і умови
Відтворюваність - це золото. Скажіть читачеві, як часто і за яких умов:
- Це відбувається кожного разу
- «Це перервне — приблизно одна з п’яти спроб»
- «Це тільки відбувається коли користувач має більше 100 елементів.»
- «Я **не можу відтворити це послідовно **, але це має тенденцію відбуватись після того, як сеанс був відкритий на деякий час.»
“Це спрацьовує тільки на мобільному Safari; настільні переглядачі працюють нормально.”
Слово “тільки” є потужним — воно сужає пошук значно.
Включаючи повідомлення про помилку
Никогда не перефразирую ошибку. В точности.
“На консолі показано:
TypeError: Cannot read properties of undefined (reading 'id')наcart.js:42.”
Перефразування (“деяка помилка про невідоме”) втрачає деталі, які часто вказують прямо на причину.
Слово, що вказує на певний контекст
- Це почало відбуватись після останнього розгортання
- «It used to work in the previous version.» (англійською)
- Це регресія — це працювало минулого тижня
- Це блокувальник — я не можу продовжувати тестування, поки його не виправимо»
“Це регресія з версії 2. 3 — там працював той самий поток.”
Слово “регресія” говорить команді, що те, що працювало, тепер пошкоджено, що змінює те, наскільки терміново вони його обробляють.
Що не можна робити
Чиста звітність уникає:
- Вгадування про причину, зазначені як факт (*“це, безумовно, база даних” *). Надати їх як теорії: “я гадаю, що це пов’язано з кешуванням, але я не впевнений.”
- Емоційна мова («це катастрофа»). Замість цього вказується: “this blocks all new sign-ups.”
- Три вади в одному звіті — надішліть їх окремо.
Банк фраз для звітів про вади
“Кроки для відтворення:”
- “Очевидна поведінка:” * “Справжня поведінка:” “Це відбувається постійно / періодично.” “Це відбувається тільки коли…” “Це регресія від…” “Додаток знімок екрана і повний слід стека нижче.”
До і після
** До: ** * « Вивантаження пошкоджено, будь ласка, виправте ». *
** Після: ** “Вивантаження PDF-файлів розміром більше 5 МБ зазнає невдачі в Chrome (кроки наведено нижче). Очікувалося: вивантаження файлів. Фактичний: поступ досягає 100%, тоді нічого не відбувається, немає помилок. Послідовний. Знімок екрану і журнал консолі долучено.”
Другу версію можна виправити сьогодні; перша генерує день питань.
Опис вади чітко є подарунком для того, хто її виправить — і часто це ваш майбутній я. Контрастуйте очікувані з фактичними, нумеруйте ваші кроки, дословно цитуйте помилки і точно вказуйте умови. Отримайте знання про цю просту структуру, і ваші звіти про вади стануть тими, які розробники дійсно хочуть отримати.
Навигація нюансів: Спілкування з вашого буг чітко - для не-національних розробників
Погляньмо правді в очі; технічний жаргон не завжди універсально розуміється. Навіть в межах команди, тонкі відмінності у фразування можуть значно вплинути на те, наскільки чітко позначається помилка, і, отже, на швидкість, з якою вона вирішується. Як не рідною англійською мовою, зосереджуючись на точності і ясності - особливо при описі проблем - є ключовим для демонстрації професіоналізму і сприяння ефективному співробітництву. Це не просто про те, що пішло не так; це про те, як ви описуєте це таким чином, що дозволяє іншим швидко зрозуміти, відтворити і врешті-решт виправити проблему. Це не просто про використання правильної граматики, але розуміння конкретних нюансів професійного технічного спілкування.
Одна з поширених пасток полягає в тому, що перекладаються виключно технічні терміни безпосередньо. Наприклад, замість того, щоб сказати « API повернув помилку », що може бути цілком зрозумілим для команди, знайомої з цією термінологією, розгляньте можливість формулювання цього як: « API виклик не повернув дані, що призвело до 500 Внутрішньої помилки сервера. » Це забезпечує безпосередній контекст — * що * не вдалося і * чому *. Аналогічно, при описі кроків відтворення, уникайте нечітких інструкцій, таких як « спробуйте запустити код ». Замість цього використовуйте точні дієслова і описи. « Будь ласка, запустіть npm start і перейдіть до /users/123 у вашому переглядачі; потім ви повинні спостерігати … » є набагато більш дієвим.
Важливий зсув включає в себе рух за межі простого зауваження «це пошкоджено» - фраза, яка не пропонує негайного керівництва. Намагайтеся описувати * спостережувану * поведінку. Замість « кнопка не працює », спробуйте « Після натискання кнопки « Надіслати » не відбувається жодної дії і не надається візуального зворотнього зв’ язку, який би вказував на успіх або невдачу ». Цей спосіб зосереджено на тому, що бачить і відчуває користувач, що часто є більш зрозумілим і простіше діагностувати. Пам’ ятайте, що хороший звіт про ваду не має на меті розчарувати вас; він має на меті надати корисну інформацію для когось іншого, щоб ефективно розв’ язати проблему.
Нарешті, пам’ятайте, що чітке спілкування виходить за рамки письмових звітів. Повідомлення Slack, що описують вади, повинні дотримуватися аналогічних принципів - короткі, конкретні і зосереджені на спостережуваних проблемах. Не допускайте двозначності. Замість « щось не так з входом », спробуйте « Я не можу увійти; після введення моїх даних реєстрації, я отримую повідомлення про помилку « Некоректне ім’ я користувача або пароль ». Використання точних слів створює довіру і демонструє вашу прихильність до чіткого розв’ язання проблем.