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

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

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

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

• “Я сформулював проблему перед розв’ язанням: наша поточна логіка повторних спроб спричиняє дублювання зарядів під мережевими розділами, і це конкретна проблема, яку розглядає цей RFC.” *

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

** Чесно заявивши про компроміси ** - визнання справжніх недоліків або ризиків запропонованого підходу, а не представлення його як не маючих недоліків.

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

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

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

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

• Проблема: [спеціфічний, конкретний опис того, що пошкоджено або відсутнє, і його вплив]
• «Пропозиція: [спеціфічний підхід], тому що [спеціфічні роздуми пов’язані з проблемою]»
• «Алтернативи розглянуті: [підхід А] — відхилено через [причину]. [підхід Б] — відхилено через [причину]»
• «Компроміси: цей підхід [спеціфічний мінус], в обмін на [спеціфічну перевагу]»
• «Відкриті питання: [конкретний невирішений пункт] — відгуки добре прийняті, особливо від [конкретної команди/експертизи]»

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

Ясне твердження про проблему:

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

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

Зазначити компроміс без мінімізації:

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

Запрошуючи незгоду справді, а не перформативно:

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

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

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

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

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

Наприклад, англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська мова: англійська

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

Однією з ключових областей уваги повинно бути вираження невизначеності і запрошення зворотнього зв’язку. Фрази на кшталт «Це наразі припущення…» або «Ми досліджуємо альтернативні підходи, що…» негайно сигналізують рецензентам, що ви відкриті до обговорення і не представляєте остаточного рішення. Аналогічно, при описі потенційних недоліків, уникайте надмірно наголошених тверджень на кшталт « Це * ніколи * не буде проблемою ». Замість цього, сформулюйте це як роздум: « Потенційним викликом з цим підходом є [спеціфічна проблема], яку ми в даний час досліджуємо ». Ще однією поширеною пасткою є використання надто складних структур речень. Стрімтеся до речень, які ефективно передають вашу ідею - розбиття довгих речень на коротші, більш перетравлювані, значно покращує розуміння. Пам’ ятайте, що мета RFC не в тому, щоб вразити вас своїм словником; це для того, щоб полегшити продуктивну дискусію.

Розглянемо практичний сценарій. Уявіть, що ви надсилаєте PR, що описує запропоновані зміни до системи автентифікації. Рецензент може відповісти: «Це виглядає цікаво, але я не бачу, як це вирішує проблеми з продуктивністю, які ми обговорювали минулого тижня. Чи могли б ви розібратися у очікуваному впливі?» Менш ефективною відповіддю з вашої сторони було б щось на зразок: « Ми реалізували новий алгоритм для поліпшення швидкості ». Це занадто нечітке словосполучення, яке не заохочує до обговорення. Сильнішим підходом було б: «Щоб вирішити попередні проблеми з продуктивністю, ми реалізували оптимізований алгоритм для [спеціфічної операції]. Однак, ми визнаємо, що потрібні подальші випробування, щоб повністю оцінити вплив. Ми раді отримати відгуки про те, чи відповідає ця зміна нашим цілям і чи є альтернативні стратегії, які ми повинні розглянути. Зауважте використання фраз на кшталт « ми визнаємо», « потрібні подальші тестування » і « вітаємо відгуки », активно сприяючи співпраці середовища.

Нарешті, зверніть увагу на те, як ви формулюєте питання. Замість запитання: «Це добре?», що може звучати зарозуміло, запитайте: «Які у вас думки щодо компромісів між [вигодами] і [потенційними недоліками]? Чи є інші фактори, які ми повинні розглядати?» Формулювання запитів на зворотній зв’язок таким чином демонструє повагу до досвіду інших і заохочує більш обдуману відповідь. Освоєння цих тонких нюансів не тільки покращить ясність ваших RFC, але також продемонструє, що ви активно залучені до співпраці, професійного середовища — важливих навичок для будь- якого розробника, який прагне процвітати в командному середовищі.