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

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

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

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

• “Додано: підтримка експорту звітів у файли CSV.” *

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

• “Віправлено: фільтри панелі не зберігались після оновлення сторінки.” *

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

• “Змінено: типовий розмір сторінки збільшено з 10 до 25 елементів на сторінку.” *

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

• “Застаріла: кінцева точка v1/users застаріла і буде вилучена у майбутньому випуску. Замість цього використовуйте v2/users

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

• “Зміна: тепер параметр format обов’ язковий для всіх запитів на експорт; раніше типовим був параметр JSON.” *

** Зауваження щодо міграції ** — коротка інструкція, яка супроводжує зміну, яка призведе до різких змін, і в якій описано, що саме потрібно зробити користувачам, щоб пристосуватися до змін. “Зауваження щодо міграції: оновіть всі виклики до /export, щоб явно включити ?format=json, якщо ви покладалися на попереднє типове значення.”

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

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

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

Запис елемента властивості:

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

Запис запису виправлення вади: “Відомо, що сповіщення іноді надсилались двічі, якщо користувач оновив свої параметри протягом декількох секунд після попереднього оновлення.”

Запис запису про зміну з поміткою про перенесення:

• “Зміна: поле apiKey було перейменовано на apiToken у всіх кінцевих точках. Зауваження щодо міграції: оновіть будь-який код інтеграції, що посилається на apiKey, щоб використовувати apiToken перед оновленням — стара назва поля поверне помилку 400, починаючи з цієї версії. *

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

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

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

1. Написати запис « Додано » для гіпотетичної нової можливості, зокрема, переваги для користувача.
2. Написати запис « Виправлено », який описує ваду з точки зору користувача, а не з точки зору внутрішньої причини.
3. Створити запис про зміну з приміткою щодо перенесення параметра API з перейменованою назвою.

Наприклад, слово «навигатор» означає: «навигатор» — професійний навігаційний пристрій

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

Однією з поширених пасток є надмірна залежність від надто формальної мови або технічного жаргону, коли метою є ясність. Фрази на кшталт «використання» або «реалізація» можуть звучати занадто громіздко і заплутано, особливо для користувачів, які не глибоко залучені в процес розробки. Замість цього, віддавайте перевагу прямим і коротким заявам. Наприклад, замість того, щоб сказати « Інтеграцію нової кінцевої точки API завершено », розгляньте « Ми додали нову кінцеву точку API для поліпшення доступу до даних ». Аналогічно, коли ви обговорюєте зміни, які є важливими для чіткого повідомлення, уникайте абстрактних описів, на зразок « зміни у всій системі ». Розгляньте це з точки зору впливу на користувача: « Це оновлення вимагає від вас оновлення вашої програми до версії 2. 5, щоб забезпечити продовження функціонування »

Іншою областю, яка вимагає уваги, є передбачення потенційних питань і активне їх вирішення в самому записі журналу змін. Хороший спосіб - це включити коротке, непрофесійне пояснення поряд з технічними деталями. Це демонструє передбачення і зменшує кількість подальших запитів. Розглянемо повідомлення Slack під час перегляду коду: «Привіт команда, я просто хотів позначити, що ця зміна вводить незначну залежність від lodash. Це звичайна бібліотека, але користувачі повинні знати про це.» або в PR-описі, «Ця рефакторизація покращує продуктивність, зменшуючи непотрібні запити до бази даних — очікуйте швидшого завантаження»

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