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

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

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

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

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

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

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

• “Шлях міграції: замінити виклики до GET /v1/users/:id на GET /v2/users/:id. Форма відповіді в основному така ж, за винятком поля name, яке тепер розділене на firstName і lastName — дивіться приклад нижче для точного до-і-після.”*

** Breaking vs. non-breaking ** - класифікація того, чи вимагає заміна застарілого API змін коду з боку споживача, що визначає, наскільки терміново і помітно повідомлення має бути повідомлено.

• “Це зміна, яка порушує, а не не порушує — форма відповіді змінюється, отже, кожному користувачеві слід оновити свій код аналізу. Саме тому ми даємо повідомлення за шість місяців і надсилаємо прямі електронні листи, а не просто запис у журналі змін»

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

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

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

Ясно зазначте обидві дати: *“Зауваження щодо застарівання: кінцева точка /v1/search буде застаріла з 1 березня 2027 року. Він продовжить функціонувати до дати закінчення 1 вересня 2027 року, через шість місяців, після чого запити до нього повернуть 404. * ”

Надання конкретного шляху міграції:

• “Шлях міграції: замінити /v1/search?q=term на /v2/search?query=term. Зауважте зміну назви параметра з q на query. Формат відповіді інакший ідентичний, тому більшість споживачів буде потрібно тільки оновити запит, а не їх розбір відповіді. ”*

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

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

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

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

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

Національні мови: мова рідних, мова носіїв мов інших народів

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

По-перше, часова мова часто складна. Фрази на кшталт «в найближчому майбутньому», «незабаром» або «в найближчі кілька місяців» завантажені неявними хронологіями, які можуть не бути відразу очевидними для когось, хто звик до різних способів виражання часу. Замість того, щоб покладатися на нечіткі терміни, прагніть до точності. Сказати « Ця кінцева точка буде вилучена 31 грудня 2024 року » набагато ефективніше, ніж « Ми повідомимо вас незабаром. » Розгляньте можливість додавання докладної хронології: « Фаза 1 — Попереджувальні повідомлення з’ являться в API з 1 липня 2024 року. Фаза 2 — кінцева точка більше не буде приймати запити починаючи з 1 січня 2025 року. » Цей шаровий підхід забезпечує ясність і зменшує неоднозначність навколо фактичного впливу.

По-друге, поняття «міграційних шляхів» потребує ретельного пояснення. Просто сказати «мігрувати до кінцевої точки B» недостатньо. Вам потрібно дати напрямок. Наприклад, замість того, щоб сказати « Будь ласка, перенесіть ваш код до кінцевої точки B », спробуйте сказати « Щоб продовжити використання цієї функціональності, вам слід оновити вашу програму, щоб використовувати нову кінцеву точку B, яка пропонує покращені можливості швидкодії і безпеки. Ми задокументували процес міграції тут: [посилання на документацію].” Використання активного голосу — « вам потрібно » — загалом є яснішим, ніж пасивні конструкції, такі як « код повинен бути мігрований »

Нарешті, пам’ ятайте, що повідомлення про застарілий API є по суті * зміна *. Позитивна структура цієї зміни, визнаючи її вплив, може сприяти більш співпрацюючому середовищу. Замість того, щоб зосередитися виключно на тому, що вилучається, підкресліть переваги нового підходу: «Якщо ми розвиваємо нашу платформу для покращення стабільності і продуктивності, ми виходимо на пенсію Endpoint A. Цей перехід дає нам змогу ввести [нову функцію] і оптимізувати загальну ефективність системи. » Фрази на зразок « перехід до » або « перехід до » можуть пом’якшити вплив усунення і вказати на активний, а не реактивний підхід.