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

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

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

---

Що таке RFC?

RFC (Request for Comments) — це структурований документ, який використовується в інженерних організаціях для запропонування значних змін, нових систем або архітектурних рішень. На відміну від квитка або повідомлення чату, RFC розроблений для ретельного читання, обговорення і, врешті-решт, прийняття або відхилення з записаною логікою.

RFC існують у таких компаніях, як Google (Design Docs), Amazon (1-Pagers і 6-Pagers), Rust (офіційний процес RFC) і безліч стартапів, які неформально прийняли цей шаблон. Назва має менше значення, ніж ідея: записати її, поділитися нею, повторювати.

---

Структура Strong RFC

1. Європа Заголовок і метадані

Ваша назва повинна бути конкретною і орієнтованою на дію. Уникайте нечітких заголовків, наприклад, « Покращення бази даних ». Надає перевагу:

• Замінити Redis Session Store з DynamoDB для Multi-Region Failover
• «Введення ставки обмеження середовища по всіх публічних API кінцевих пунктів»

Включити метадані: ** Автор **, ** Стан ** (Чернетка / Переглядається / Прийнято / Відхилено), ** Створено **, ** Останнє оновлення ** і ** Зацікавлені сторони **.

2-й. Резюме (TL; DR)

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

** Ключові фрази для резюме: **

• Цей документ пропонує…»
• «Ми зараз стикаємося з проблемою… Цей RFC рекомендує…»
• «Це питання — наші дні…»

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

3. Опис проблеми

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

** Ключові фрази: **

• «Теперішній підхід страждає від…»
• «Це стає бутербродом, коли…»
• Під час тестування на навантаження, ми спостерігали, що… ”
• «Причина зникнення — це…»
• Це призводить до…, що прямо впливає на…»

Будь конкретним. Включіть номери, посилання на події або посилання на панелі керування. « Служба іноді перевищує час очікування » є слабким. « Затримка p99 для цієї кінцевої точки перевищує 2000 мс під час максимального навантаження, про що свідчать три виробничі події у першому кварталі (INC- 441, INC- 512, INC- 589) » є сильним.

4. Пропоноване рішення

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

** Ключові фрази: **

• «Пропозиція про введення…»
• «На високому рівні архітектура працює наступним чином:…»
• Цей підхід відрізняється від нинішньої системи трьома ключовими способами: … ”
• «Міграція буде проходити в два етапи:…»

5. Розглянуті альтернативи

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

** Ключові фрази: **

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

6-й. Вплив і ризики

Будь чесним щодо ризиків. RFC, який прикидається, що немає ніяких недоліків, руйнує довіру.

** Ключові фрази: **

• «Перший ризик — це… який ми зменшимо за допомогою…»
• Ця зміна вимагає скоординованого розгортання по всіх… командах»
• «Rollback є простим: ми можемо повернутися до попередньої конфігурації за допомогою…»
• «Вплив на продуктивність очікується незначним, на основі наших еталонів (див. додаток A)»

7. Відкриті питання

Список того, що ви ще не знаєте. Це сигналізує про інтелектуальну чесність і запрошує зосередитися на зворотному зв’язку.

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

---

Тон і стиль

RFC повинні бути прямими, але спільними. Уникайте пасивного-агресивного хеджування («очевидно, що поточна система жахлива») і уникайте перекваліфікації кожної претензії («можливо, це може бути можливо, що ми могли б розглянути…»). Стремитесь быть уверенным и коллегиальным.

Використовуйте першу особу множини («ми рекомендуємо», «наше дослідження показує»), а не безособовий пасив («рекомендується, що»). Множина створює відчуття спільної власності.

---

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

• ** Обґрунтування ** — причини, що стоять за рішенням
• Таргетинг - прийняття одного недоліку в обмін на перевагу
• ** Обсяг ** — межі того, що охоплює RFC
• ** Зацікавлена особа ** — особа або команда, на яку впливає рішення
• ** Консенсус ** — широка згода серед рецензентів
• ** План відновлення ** — визначений спосіб скасування зміни у разі її невдачі
• ** Тривале виконання ** — обробка, яка переживає аварії і безпечно повторює спроби
• ** Спостережливість ** — здатність стежити за поведінкою системи і розуміти її

---

Необхідно уникати помилок

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

** Без конкретних показників. ** Пропозиції без даних є думками. Подтвердите каждое утверждение цифрами.

Поховали вывод. Поставьте свою рекомендацию рано. Это техническая литература, а не детективный роман.

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

Добре написаний RFC зрозумілою англійською мовою - це прискорювач кар’єри. Він демонструє системне мислення, навички спілкування і лідерство - все без офіційного титулу управління. Начни писать.

Наприклад, мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова мови: мова

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

Одна з найчастіших проблем виникає під час перегляду коду. Уявіть, що ви отримали коментар на зразок: « Ця функція могла б отримати користь від деяких змін — розгляньте можливість використання більш описової назви змінної ». Хоча це виглядає просто, але фраза « користь від » є ідіоматичною і може здатися нечіткою. Нерідний мовець може відразу ж перекласти його буквально: «Ця функція отримує перевагу від…». Це не неправильно, але в ньому немає очікуваного професійного тону. Замість цього, кращою відповіддю буде: «Я помітив, що temp використовується тут; перейменування його на щось більш описове, наприклад, result, поліпшить читабельність і підтримку». Ключова відмінність полягає в тому, що використовуються конкретні пропозиції, а не абстрактні переваги. Аналогічно, повідомлення Slack, що вимагає зворотного зв’язку на PR, може містити такі фрази, як «Будь ласка, перегляньте це ретельно» - інструкція, яка відчувається вимогливою без контексту. Переглянутий підхід може бути таким: “Чи можете ви подивитися на зміни? Мене особливо цікавлять ваші думки щодо нової реалізації журналювання. » Формування запитів як запрошень до співпраці майже завжди є більш ефективним.

Іншою областю, яка викликає занепокоєння, є створення введення і резюме RFC. Часто ці розділи містять надто формальну або складну мову. Використання фраз на кшталт «Найважливіше, щоб…» або «Поточна архітектура вимагає…» негайно сигналізує про відсутність співпраці і може залякати рецензентів. Замість цього, прагніть до прямоти: «Цей документ описує запропоновані зміни до служби автентифікації…». Крім того, при описі потенційних недоліків, які є * обов’ язковими * у документі RFC, уникайте надмірно обережних висловлювань на зразок « Можливо, що … » Замість цього, вкажіть ризик чітко, але коротко: « Ця зміна створює потенційне в’ язичне горло продуктивності під великим навантаженням ». Нарешті, пам’ ятайте, що використання активного голосу постійно покращує ваші описи. Пасивні конструкції («Система буде вплинена») можуть затемнити відповідальність і ускладнити для рецензентів зрозуміти, хто відповідає за вирішення будь-яких питань. Сфокусуйтесь на * вас * - авторі - пропонуючи рішення.