Writing Effective Error Messages in English: Principles and Examples
Як написати чітке, дійсне повідомлення про помилку англійською мовою для програмного забезпечення — з хорошими та поганими прикладами, словником станів помилок і вправами з переписування.
Повідомлення про помилки є найчастіше читається записом у більшості програм, і найбільше ігнорується. Користувачі стикаються з ними в моменти розчарування або збою — найгірший можливий час для нечіткої, технічної або обвинувачувальної мови. Писання чітких, людських повідомлень про помилки є навичкою, яка знаходиться на перетині технічного письма, UX і англійської комунікації. Цей посібник охоплює основні принципи і надає вам конкретні поради щодо переписування до/ після.
П’ять принципів добрих помилкових повідомлень
1. Будь конкретним
Добре написане повідомлення про помилку говорить користувачеві, що саме сталося не так. Неясне повідомлення змушує користувача вгадати.
| Bad | Good |
|---|---|
| ”An error occurred." | "Your session expired. Please sign in again." |
| "Something went wrong." | "We couldn’t save your changes — the server returned a timeout." |
| "Invalid input." | "Your password must be at least 8 characters and include one number.” |
Специфічність не стосується технічних деталей - це стосується чіткого повідомлення відповідного факту.
2. Бути дієздатним
Кожне повідомлення про помилку має відповідати на неявне питання: * « Що мені робити тепер?» * Якщо користувач прочитає повідомлення і не знає, що робити далі, повідомлення про помилку було скасовано.
- ** Немає чіткої дії: ** « Спроба виконання запиту зазнала невдачі. »
- ** Actionable: ** « Не вдалося обробити ваш запит. Будь ласка, перевірте своє підключення до Інтернету і спробуйте знову»
Іноді дія буде « зв’ язатися з підрозділом підтримки » або « спробувати знову пізніше ». Це нормально — просто вкажіть це чітко.
3-й. Не звинувачуйте користувача
Звинувачувати - це неправильно і відчужено. Більшість помилок спричинено обмеженнями системи, прогалинами у проектуванні або крайовими випадками, яких розробник не передбачав.
| Blaming | Neutral |
|---|---|
| ”You entered an invalid date." | "Please enter a date in the format DD/MM/YYYY." |
| "You must agree to the terms." | "To continue, please accept the Terms of Service." |
| "You’ve exceeded the limit." | "You’ve reached the maximum of 5 projects on the free plan. Upgrade to add more.” |
Зауважте, що нейтральні версії також більш специфічні і дійсні — хороші повідомлення про помилку природно поєднують всі п’ять принципів.
4-й. Включити кроки відновлення
Якщо це можливо, скажіть користувачеві, як саме виправити проблему, а не лише в чому вона полягає.
- “Ваша кредитна карта була відхилена. Будь ласка, перевірте номер карти, дату закінчення терміну дії та адресу для розрахунків, а потім спробуйте знову»
- « Ця адреса електронної пошти вже зареєстрована. Замість цього ввійдіть, або скасуйте пароль, якщо ви його забути»
- “Вивантажений вами файл має розмір 15 МБ. Будь ласка, зменшіть його до менш ніж 10 МБ перед завантаженням»
Кроки відновлення перетворюють тупик на шлях вперед.
5-й. Уникайте технічного жаргону
Якщо аудиторія не має чітко визначених технічних знань (консоль розробника, інструмент CLI), уникайте використання внутрішньої технічної мови.
| Jargon | Plain English |
|---|---|
| ”HTTP 500 Internal Server Error" | "Something went wrong on our end. Please try again in a moment." |
| "ECONNREFUSED: Connection refused to 127.0.0.1:5432" | "We can’t reach our database right now. Please try again later." |
| "Null reference exception in UserService" | "We couldn’t load your profile. Please refresh the page.” |
Словник помилкових станів
Різні типи помилок мають різні стандартні описи англійською мовою. Використання послідовного, розпізнаного словника допомагає як користувачам, так і розробникам.
| Error State | Technical Code | User-Facing Language |
|---|---|---|
| Not found | 404 | ”We couldn’t find that page.” / “This resource no longer exists.” |
| Unauthorised | 401 | ”Please sign in to continue.” |
| Forbidden | 403 | ”You don’t have permission to access this.” |
| Timeout | 408 / 504 | ”The request took too long. Please try again.” |
| Server error | 500 | ”Something went wrong on our end. We’re looking into it.” |
| Validation error | 422 | ”Please check the highlighted fields and try again.” |
| Rate limited | 429 | ”You’ve made too many requests. Please wait a moment before trying again.” |
| Conflict | 409 | ”This record was modified by someone else. Please refresh and try again.” |
| Gone | 410 | ”This content has been permanently removed.” |
Перезапис повідомлення про помилку
Ось п’ ять реальних повідомлень про помилки, переписаних за допомогою принципів, описаних вище.
Перезапис 1: Загальна помилка сервера
** Оригінал: **
Помилка 500. Спробуйте знову пізніше.
** Переписано: **
Что-то пошло не так с нашей стороны. Нас проінформували і ми розслідуємо це. Будь ласка, спробуйте ще раз за кілька хвилин.
** Зміни: ** Названо помилку простою мовою, запевнено користувача, що команда знає про це, вказано очікуваний час.
Перезапис 2: Помилка вивантаження файла
** Оригінал: **
Файл відхилено.
** Переписано: **
Не вдалося завантажити ваш файл. Підтримуються лише файли JPG, PNG і PDF, а максимальний розмір файла — 10 МБ. Будь ласка, перевірте ваш файл і спробуйте знову.
** Зміни: ** Вказано причину відхилення, список чинних параметрів, вказано дію відновлення.
Перезапис 3: Помилка реєстрації
** Оригінал: **
Некоректні дані реєстрації. Помилка автентифікації.
** Переписано: **
Введені вами адреса електронної пошти або пароль не збігаються з нашими записами. Будь ласка, спробуйте ще раз або скасуйте свій пароль, якщо ви його забути.
** Зміни: ** Вилучено жаргон (« реєстраційні дані », « автентифікація »), зменшено розмір рамки, запропоновано шлях відновлення.
Перепис 4: Перевірка форми
** Оригінал: **
Ви ввели некоректні дані у полі 3.
** Переписано: **
Будь ласка, введіть коректний номер телефону. Ми приймаємо номери Великої Британії у форматі 07XXX XXXXXX або +44 7XXX XXXXXX.
** Зміни: ** Назва поля у вигляді, який зрозумілий для користувача, надано точний приклад форматування.
Перезапис 5: Помилка дозволів
** Оригінал: **
Доступ заборонено. У вас немає необхідних прав.
** Переписано: **
У вас немає прав для перегляду цієї сторінки. Якщо ви вважаєте, що це помилка, зверніться до адміністратора вашого облікового запису.
** Зміни: ** Вилучено « пропущено » (незначна помилка), додано шлях відновлення для кращих випадків.
Запис повідомлень про помилки для різних аудиторій
Принципи, описаний вище, застосовуються до всіх випадків, але реєстр змінюється залежно від контексту:
- ** Програма для побутових користувачів (не технічні користувачі): ** Проста англійська, приємний тон, мінімальний жаргон, завжди включає кроки відновлення.
- ** Інструмент API/ CLI для розробників: ** Потрібно додати більше технічних відомостей; включіть коди помилок, відповідні назви полів, методи HTTP. Розробники хочуть точності.
- ** Панель адміністратора: ** Середня позиція — будьте конкретними щодо того, що не вдалося, включайте технічні ідентифікатори, але уникайте необроблених слідів стека.
Ключеві моменти
- ** Особливі, реальні, не звинувачувальні** повідомлення про помилки зменшують розчарування користувачів і зменшують кількість квитків на підтримку.
- Завжди відповідайте на питання: “Що мені робити тепер?”
- Використовуйте просту англійську мову для повідомлень, адресованих споживачам; забудьте про технічну мову для контекстів, адресованих розробникам.
- Послідовність у словнику (використання однієї мови для одного стану помилки у всій програмі) зменшує плутанину.
- Повідомлення про помилки — це можливість показати вашу компетентність і турботу про інших — скористайтеся цим.
Наприклад, англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська
Написання ефективних повідомлень про помилки є основою хорошого спілкування з розробниками. Ми вже описали основні принципи — ясність, специфічність, корисні поради — але давайте звернемося до особливо важливого питання для розробників, чия перша мова не є англійською: освоєння тонких нюансів професійної фразування і словникового запасу при описі проблемних станів. Це не просто про передачу * що * пішло не так; це про те, щоб зробити це таким чином, що мінімізує розчарування і заохочує продуктивне вирішення проблем. Багато розробників, навіть тих з сильними технічними навичками, борються з перекладом підходу їх рідної мови до повідомлення про помилку на чітку, коротку англійську. Це може призвести до повідомлень, які технічно точні, але в кінцевому підсумку не допоможуть або навіть заплутують когось, хто намагається зрозуміти і виправити проблему.
Однією з поширених пасток є покладання на надто буквальні переклади технічних термінів. Наприклад, фраза «Resource unavailable» (ресурс недоступний), яка може здатися абсолютно простою в іншій мові, може бути нечіткою і неінформативною в англійській. Розгляньте контекст. Користувачеві, який натискає кнопку, що викликає помилку запиту бази даних, потрібне щось більше, ніж просто вказівка на те, що « ресурс не був доступним ». Метою є надати користувачеві знання про те, * чому * ресурс не був доступним. Замість цього, повідомлення буде на зразок « Під час спроби отримання даних для вашого запиту на сервері сталася помилка. Будь ласка, спробуйте знову пізніше або зверніться до служби підтримки, якщо проблема зберігається.» надає негайний контекст і пропонує можливі рішення. Аналогічно, коментар перегляду коду, що говорить «Неправильний вхід» набагато менш корисний, ніж «Поле username повинно містити принаймні 6 символів»
Давайте подивимося, як це може проявитися в реальному світі комунікації. Уявіть, що ви переглядаєте запит на завантаження. Розробник пише: « Помилка: Система зазнала невдачі ». Ви можете просто відповісти « Виправте це ». Але, щоб бути більш підтримуючим і інструктивним — особливо для тих, хто вивчає англійську — ви можете сказати: « Це повідомлення занадто нечітке. Чи можете ви дати більше інформації про природу несправності? Зокрема, що відбувалося, коли сталася помилка, і чи є якісь відповідні журнали або стеки слідів, які могли б допомогти діагностувати проблему?» Цей підхід використовує точний словник («природа помилки», «відповідні журнали», «стеки слідів») — терміни, які часто зустрічаються у професійних дискусіях з розробки програмного забезпечення — щоб заохотити більш докладне пояснення. Це стосується моделювання типу зворотнього зв’язку, який ви очікуєте отримати, і демонстрації розуміння процесу усунення несправностей.
Нарешті, пам’ятайте, що короткість є ключем, але не жертвуйте ясністю заради стислості. Спробуйте використовувати речення, які достатньо довгі, щоб передати основну інформацію, не будучи надто розгорнутими. Використання активного голосу (« Сервер зіткнувся з помилкою ») зазвичай є кращим за пасивний голос (« Сервер зіткнувся з помилкою »), оскільки він є більш прямим і простішим для розуміння. Під час створення повідомлень про помилку, подумайте про те, як ви поясните проблему колегі, який не має досвіду роботи у проекті — це найкращий спосіб переконатися, що ваше спілкування буде доступним і ефективним.