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

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

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

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

• “Я зробив зміни, які стосуються користувачів: тепер ви можете експортувати звіти безпосередньо до формату CSV, замість того, щоб відкривати сторінку з технічними відомостями щодо нової служби експорту.” *

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

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

• “Я позначив зміну, що призведе до різкого зростання: існуючі інтеграції API, що використовують кінцеву точку v1, потрібно буде перенести на v2 до кінця наступного місяця.” *

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

• “Я перетворив виправлення на простий результат: звіти з більше ніж 10 000 рядків тепер експортуються правильно, замість того, щоб просто сказати « виправлено помилку сторінкування у службі експорту. ». ”*

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

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

Приклади речення

Добре структурований запис з відомостями про випуск:

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

Позначити зміну, що порушує правила, ясним знаком:

• “Зміна: кінцева точка /v1/reports буде вилучена 1 березня. Якщо ваша інтеграція використовує цю кінцеву точку, будь ласка, перейдіть до /v2/reports, яка підтримує ті ж основні функції з додатковими параметрами фільтрування. Див. посібник з міграції, посилання нижче. *

Переклад внутрішнього виправлення вади у простий результат:

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

Чесно визнаю відомі обмеження:

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

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

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

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

1. Напишіть « Новий » запис, який описує гіпотетичну можливість з точки зору користувача, у одному реченні.
2. Переклад технічного опису вади (« виправлено виняток нульового вказівника у обробнику експорту ») у простий, зрозумілий користувачеві результат.
3. Написати повідомлення про зміну, яке містить певну дію і певну дату.

Національний склад населення: Англійська мова

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

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

Розгляньте це повідомлення Slack: « Щойно об’ єднано v2. 5. Додано поток розпізнавання користувача. Виправляє незначні помилки інтерфейсу користувача. » Людина, для якої мова не є рідною, може інстинктивно перекласти це як щось надто докладне і заплутане. Замість цього, більш відшліфований підхід буде таким: «Відкрита версія 2.5. У ній передбачено нову систему автентифікації користувача і вирішено деякі незначні візуальні проблеми. » Зауважте зміну у використанні фраз — активний голос, чітка тема, уникнення потенційно неоднозначних слів. Ці невеличкі зміни роблять велику різницю у тому, наскільки легко буде зрозуміти ваше повідомлення.

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