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

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

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

** Обсяг впливу ** — конкретні умови, за яких відбувається відома проблема, зазначені достатньо точно, щоб користувач міг визначити, чи справді вони були вплинуті, а не нечіткий опис, який залишає всіх у невідомості. “Ця проблема стосується конкретно користувачів Safari на iOS 17, які експортують PDF-файли розміром більше 10 МБ - якщо ви використовуєте інший браузер або експортуєте менший файл, ця проблема на вас не впливає.”

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

• “Як обхідне рішення, експортування двома меншими партіями замість одного великого експортування повністю уникає цієї проблеми. Це тимчасове рішення, а не виправлення, і воно більше не буде необхідним, як тільки буде вирішена основна помилка. ”*

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

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

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

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

• «Ця проблема впливає на [спеціфічний, точний обсяг] — якщо ви знаходитесь за межами цього обсягу, ви не повинні зіткнутися з нею»
• «Як тимчасове рішення, ви можете [конкретний, конкретний крок]»
• «Ми ще не маємо підтвердженої графіки виправлень, але це активно відстежується»
• «Це [незначна/косметична/значна] проблема — ми хочемо бути точними щодо її фактичної тяжкості»
• Цей запис буде оновлений, як тільки буде доступний виправлення або хронологія стане яснішою

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

Визначення обсягу відомої проблеми:

• “Відома проблема: користувачі з безкоштовним рівнем, які намагаються експортувати більше 50 рядків до CSV, побачать помилку тайм- аута. Це не впливає на платні рахунки, які не мають обмеження на рядки на експорт.”*

Надання дійсно корисного рішення:

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

Бути чесним щодо невідомої часової лінії, не залишаючи користувачів у темряві:

• “Ми ще не визначили конкретну дату виправлення, оскільки це потребує зміни у нашому експортному конвеєрі, який ми хочемо ретельно перевірити перед надсиланням. Ми оновимо цей розділ, як тільки у нас буде підтверджена хронологія».*

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

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

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

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

Розвиток мовлення: мовні проблеми в мовленнєвій діяльності

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

Розглянемо сценарій: Під час перегляду коду, розробник з Німеччини надсилає запит на витягнення з коментарем щодо змін одного з членів вашої команди. У коментарі просто написано: «Це не працює». Хоча це і просте англійською, це може бути сприйнято як надто тупе або без контексту для когось, чия перша мова не англійська. Це відразу ж викликає питання: Не працює — що саме не працює? Які очікувалися результати? Більш конструктивним формулюванням буде щось на зразок: «Я зіткнувся з проблемою, коли логіка перевірки даних неправильно застосовувалася до вводу користувача в цьому розділі. Я додав перевірку, щоб вирішити цю проблему». Цей пункт надає вам негайний контекст і демонструє активний підхід до розв’ язання проблеми.

Аналогічно, в Slack, ви можете отримати повідомлення від колеги, який тестує нову функцію. Вони вводять: «Програма зазнає аварії». Це одне речення можна розглядати як звинувачення або просто заяву про невдачу. Краще відповідь — і така, що показує співчуття для когось, хто потенційно бореться з англійською — була б: «Гаразд, дякую, що повідомили нас! Можете описати кроки, що призвели до аварії? Будь- які повідомлення про помилки, які ви бачили, також будуть дуже корисними. » Додані питання спонукають до подальшого дослідження і демонструють спробу зрозуміти, * як * проявляється проблема.

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