Як написати технічний RFC англійською мовою: Структура і фрази
Структура RFC (Request for Comments), опис проблеми, запропоновані рішення, альтернативи і словник рішень англійською мовою.
Якщо ви працюєте у команді, яка приймає рішення щодо архітектури або процесів, вам з часом доведеться прочитати — або написати — RFC. Для людей, для яких англійська мова не є рідною, виникають подвійні труднощі: вам слід розуміти технічний зміст * і* специфічний словник, який використовують досвідчені інженери для обговорення цього змісту. У цій статті розглянуто кожен з ключових термінів, показано, як вони використовуються у реальних розмовах, а також наведено короткий довідник, яким ви зможете скористатися під час наступного перегляду.
Що таке RFC і чому це важливо?
** RFC (Request for Comments) ** це структурована письмова пропозиція, яка описує проблему, пропонує рішення і запрошує команду або організацію обговорити її перед прийняттям рішення. Термін походить з раннього інтернету (IETF опублікував RFC для визначення протоколів), але сьогодні команди програмного забезпечення використовують його для будь-чого, від нового дизайну API до зміни стратегії розгортання.
RFC сповільнюють імпульс просто «почати кодування» — і це є функцією, а не багом. Добре написаний RFC рано висвітлює проблеми, створює сліди на папері і забезпечує ** вирівнювання зацікавлених сторін **: кожен, хто буде зачеплений рішенням, мав можливість прокоментувати.
«Перед тим, як ми розпочнемо спринт, чи може хтось написати RFC? Я хочу переконатися, що команда платформи має видимість, перш ніж ми зобов’язуємося до цього підходу»
“Ми слідуємо процесу RFC тут. Навіть невеликі архітектурні зміни потребують пропозиції дизайну, щоб ми могли зберігати запис рішення»
Основні терміни
** Проблема ** - чіткий, короткий опис проблеми, яка мотивує RFC. Хороший висновок про проблему відповідає: що не так, для кого, і чому це має значення зараз? Уникайте перескакування до рішень тут.
“Ваш виклад проблеми трохи неоднозначний. Можете оцінити шкоду? Щось на зразок «наша затримка p99 перевищує 800 мс під навантаженням» набагато сильніше, ніж «сервіс повільний»
«Я б запропонував відокремити висловлювання проблеми від мотиваційного розділу — зараз вони змішані разом і важко побачити, що ви насправді намагаєтеся виправити»
** Мотивація ** — * чому * за пропозицією. У той час як опис проблеми описує * що * пошкоджено, мотивація пояснює * чому вирішення цього питання важливо * для бізнесу або користувачів. Хороша мотивація включає дані, зворотній зв’язок від користувачів або аргументи вартості.
“Розділу мотивації потрібно більше контексту. Які будуть наслідки для бізнесу, якщо ми не розберемося з цим? Конкретне число допоможе отримати підписання»
“Мені подобається, що ви пов’язали мотивацію з нашим OKR на досвіді розробника. Це допоможе з вирівнюванням зацікавлених сторін, коли це піде на перегляд архітектури»
Пропоноване рішення — головна рекомендація RFC. У цьому розділі описано, * що* ви бажаєте зробити і * як* це працює. Вона повинна бути достатньо докладною, щоб переглядачі могли оцінити її реалізованість, але не повною специфікацією реалізації.
“Пропоноване рішення виглядає твердим, але мені бракує деталей про те, як ви плануєте обробляти зворотну сумісність. Чи можете ви додати абзац про шлях міграції?»
“Ваш запропонований варіант припускає, що ми вже маємо прапорці функцій на місці. Чи є це безпечним припущенням для всіх середовищ?»
** Розглянуті альтернативи ** — розділ, у якому наведено список інших підходів, які ви оцінювали перед тим, як прийняти рішення щодо запропонованого рішення. Пропуск цього розділу є червоним прапорцем; це означає, що автор не дослідив проблемний простір досконало.
“Я бачу тільки один запис в розділі альтернатив, які розглядаються. Чи ви розглядали можливість використання черги повідомлень замість прямого виклику HTTP? Цей аналіз компромісів був би корисний»
«Ми відкинули варіант GraphQL — він в розглянутому розділі альтернатив з аргументацією. Коротка версія: команді бракує досвіду, а графік дуже жорсткий»
** Аналіз взаємозв’ язку ** — порівняння плюсів і мінусів кожного варіанту, включаючи обраний варіант. Хороший аналіз компромісів є чесним: він визнає недоліки запропонованого рішення, а не прикидається, що воно ідеальне.
“Я ціную чесний аналіз компромісів. Визнаючи, що цей підхід збільшує складність операцій, це правильне рішення — ми краще знаємо заздалегідь, ніж виявимо його в виробництві»
“Чи можете ви розширити аналіз компромісів, щоб включити витрати на серіалізацію / десеріалізацію? З високочастотними подіями, це надлишок може бути значним»
Структурування документа RFC
Критерії успіху — вимірювані умови, які визначають, коли пропозиція досягла своєї мети. Без критеріїв успіху неможливо оцінити, чи була реалізація успішною.
“Які критерії успіху тут? Я хочу знати, як виглядає «зроблено» — це ціль затримки, рівень помилок або щось інше?»
«Додамо критерії успіху до прийняття RFC. Моя пропозиція: p95 час відповіді нижче 200 мс і нульове збільшення рівня помилок за 2-тижневий канарський період. ”
** Відкритий запит ** — список нерозв’ язаних питань, які автор RFC визнає, але не може відповісти сам. У цьому розділі запропоновано певні введення і запобігається блокування RFC у разі невизначеності.
“Розділ відкритих питань дуже корисний. Я можу відповісти на питання 3 — політика зберігання даних становить 90 днів, тому ваша логіка архівування повинна обробляти цей крайній випадок»
“Будь ласка, не позначайте цей RFC як готовий для перегляду, поки ви не вирішите або принаймні не розсортуєте відкриті питання. Там є два блокатори»
** Запис рішення ** — постійний журнал, що містить інформацію про те, * чому * було прийнято рішення, включаючи контекст, оцінювані варіанти і результат. Навіть коли RFC відкидається, запис рішення зберігає обґрунтування для майбутніх інженерів.
“Я не зміг знайти запис рішення, чому ми відійшли від REST тут. Хтось знає, чи був RFC? Ми можемо бути на порозі повторного судового розгляду старого рішення»
«Завжди оновлювати запис рішення після зустрічі з перегляду RFC, навіть якщо результатом є «ми вирішили почекати». Майбутнє, яке ти будеш дячити сьогодні тобі»
Рішення РНК: мова і етикет
Рішення зустрічі RFC є синхронною (або асинхронною) сесією, де зацікавлені сторони обговорюють пропозицію і рухаються до рішення. Знаючи правильні фрази, ці зустрічі стають менш стресовими.
Ви почуєте такі типові фрази:
- “Я залишив деякі коментарі на документі — нічого не блокує, тільки гниди.”
- “Я +1 на запропоноване рішення, але я хотів би побачити відкриті питання вирішені спочатку.”
- “Чи можемо ми обговорити альтернативи в часовому проміжку? Ми були на ній 20 хвилин.»
- “Давайте розглянемо деталі реалізації поза мережею — це стає занадто глибоким для перегляду RFC.”
** Розв’ язання коментарів ** стосується процесу розгляду письмового відгуку рецензентів перед прийняттям рішення. Від авторів очікується або виправити поставлену проблему, або пояснити, чому вони не погоджуються.
“Я прочитала всі коментарі. Дві з них вирішені, одна я відкинув з запискою — чи можете ви поглянути і підтвердити, що ви задоволені?»
“Розв’ язання коментарів блокує об’ єднання. Ми не можемо прийняти RFC, поки кожна відкрита ниточка не буде або адресована, або позначена як не буде виправлена з якоїсь причини»
Як використовувати їх у розмові
Зрозуміти умови - це лише половина справи. Ось як їх можна використовувати в повсякденному спілкуванні.
LGTM проти NACK — два скорочені висновки, використовувані в перегляді коду і RFC. LGTM (« Looks Good To Me ») сигналізує схвалення. NACK (« Negative Acknowledgement ») сигналізує заперечення блокування.
“Я додав свій LGTM до документа. Один незначний ніт на назві методу серіалізації, але це не блокування»
«Я збираюся NACK цей RFC наразі. Аналіз компромісів не розглядає суверенітет даних, і це важка вимога для наших клієнтів ЄС»
Коли RFC досягає кінця свого періоду перегляду, його результат оголошується офіційно:
-
- “RFC прийнято. Ми перейдемо до реалізації в наступному спринті.”*
-
- “РФК відхилено. Див. запис рішення для обґрунтування і наступних кроків.”*
«RFC приймається з умовами — нам потрібно вирішити відкрите питання про поведінку повторних спроб, перш ніж ми вирізаємо перший випуск»
«Після трьох тижнів перегляду, RFC відкидається. Консенсус був, що вартість міграції переважає користь в нашому теперішньому масштабі. Реєстр рішень було оновлено»
Пропозиція проекту іноді використовується взаємозамінно з RFC, але в деяких організаціях це відноситься до легшого документа - менш формального, коротшого і використовується для менших рішень, які не вимагають повного вирівнювання зацікавлених сторін.
«Для такої невеликої зміни, пропозиції дизайну у вікі, напевно, буде достатньо. Вам не потрібно проходити повний процес RFC»
«Я почав з пропозиції дизайну, щоб отримати ранній зворотній зв’язок, а потім розширив його в належний RFC, як тільки підхід був перевірений»
Краткий справочник
| Term | Meaning |
|---|---|
| RFC (Request for Comments) | Structured proposal document inviting team review before a decision |
| Problem statement | Clear description of what is wrong and why it matters |
| Proposed solution | The recommended approach to solving the problem |
| Alternatives considered | Other options evaluated and reasons for rejecting them |
| Trade-off analysis | Honest comparison of pros and cons for each option |
| Success criteria | Measurable conditions that define a successful outcome |
| Open questions | Unresolved issues explicitly flagged for input |
| Decision record | Persistent log of why a decision was made |
| LGTM / NACK | Approval / blocking objection in a review |
| Stakeholder alignment | Ensuring all affected parties understand and accept the decision |
Писання RFC англійською мовою — це навички, які покращуються з практикою. Словниковий запас, який міститься у цій статті, допоможе вам впевнено брати участь у перегляді, надавати точні зворотні зв’ язки і писати пропозиції, яким довірятимуть ваші колеги. Почати читання можна з перегляду декількох прийнятих у вашій організації документів RFC — зверніть увагу на поведінку кожного з розділів і зверніть увагу на те, як досвідчені інженери структурують свій аналіз компромісів. Попробуй написать сам, даже для небольшого решения. Артефакт, який ви створите, збережеться після закінчення зустрічі, на якій його обговорювали.