How to Write Technical RFCs: Advanced Language Guide (англійською)

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

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

Мотивація Розділ мотивації RFC пояснює, чому пропозиція існує — яку проблему вона вирішує і чому вирішення її має значення зараз. Сильна мотивація заслуговує уваги читача і встановлює ставки для рішення.

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

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

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

** Розглядається альтернатива ** Розглянута альтернатива є рішенням, яке було оцінено і відхилено на користь запропонованого підходу. Документування розглянутих альтернатив показує інтелектуальну суворесть і допомагає майбутнім читачам зрозуміти, чому інші підходи не були обрані.

• Приклад: « Однією з альтернатив було використання черги повідомлень замість прямих викликів HTTP. Ми відкинули це, тому що це додасть операційні витрати без значного поліпшення надійності для нашого випадку використання. ”*

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

Нерозв’язане питання Нерозв’язане питання — це питання, на яке автор RFC визнає, що не має чіткої відповіді, запрошуючи спільноту внести свій внесок у роздуми. Бути відкритим про те, що ви не знаєте, є ознакою інтелектуальної чесності в написанні RFC.

• Приклад: « Одним з невирішених питань є те, чи буде рівень кешування залежати від регіону, чи буде достатньо одного глобального кешу. » *

Структура ефективного RFC

** Резюме: ** Один абзац, що описує пропозицію на найвищому рівні. Має бути доступним для читання всім користувачам організації.

** Мотивація: ** Яку проблему ми вирішуємо, і чому це важливо? Включити дані, де це можливо.

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

Компроміси і недоліки: Чесна оцінка витрат на запропонований підхід.

** Розглянуті альтернативи: ** Що ще було оцінено? Чому відмовили?

Нерозв’язані питання: Що нам ще потрібно з’ясувати?

** План впровадження: ** Як це буде здійснено? Хто відповідає? Який час?

Корисні фрази для написання RFC

• Цей RFC пропонує новий підхід до X, мотивований потребою в Y
• “Поточне реалізація має такі обмеження:…”
• Ми оцінили три альтернативні підходи, перш ніж вирішитись на цей дизайн
• «Головна перевага цього підходу є X; відповідний компроміс є Y.»
• «Ми розглядали можливість використання Z, але відмовилися від нього, тому що…»
• «Одне відкрите питання, яке потребує подальшого дослідження, це…»
• Ця пропозиція була обговорена з зацікавленими командами і має їх тимчасову підтримку. ”
• «Впровадження буде проходити в два етапи: …»
• «Зворотній зв’язок запрошується на всі розділи, але особливо на запропонований контракт API в розділі 3»
• Цей RFC замінює RFC-0042, який пропонував подібний, але менш масштабований підхід

Підтримка розділу мотивації

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

Слабкий: «Поточний рівень кешування використовує Redis з одним основним вузлом»

Strong: «Наша служба оплати переживає піки затримки під час періодів пікового трафіку, що призводить до того, що 12% користувачів залишають свою корзину до завершення покупки. Профілювання вказує, що вузьке місце є нашим кешом Redis з одним вузлом, який стає насиченим під час пікового навантаження»

Використовуйте дані, щоб встановити надійність. Конкретні числа - коефіцієнти помилок, вимірювання затримки, цифри вартості - роблять мотивацію конкретною і важко відкинути.

Обробка заперечень в мові RFC

Хороший RFC передбачає найбільш очевидні заперечення і активно звертається до них в розділах «Відхилення» або «Розглянуті альтернативи». Це більш переконливо, ніж чекати, коли тобі поставлять запитання.

Використовуйте поступливу мову, щоб визнати заперечення справедливо перед тим, як їх спростувати: “Хоча це правда, що цей підхід вводить додаткову складність, операційні витрати виправдані значним поліпшенням надійності, яке він забезпечує”

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

Розробка мови RFC

Точна мова є важливою в технічних документах. Неясні фрази сприяють неправильному тлумаченню і довгим гілам коментарів. Порівняти:

Неясне: «Система повинна швидко відповідати на запити користувачів» Точне: «Система повинна відповідати на 95% запитів користувачів протягом 200 мс, як виміряно протягом 5-хвилинного рухомого вікна»

Використовуйте « must », « should » і « may » послідовно згідно з RFC 2119: « must » для абсолютних вимог, « should » для сильних рекомендацій і « may » для необмежених поведінок.

Практичні рекомендації

Написати односторінковий RFC (близько 400 слів) для вигаданої технічної зміни — наприклад, міграції служби з REST до gRPC, прийняття нової бази даних або введення нової стратегії розгортання. Включіть резюме, мотивацію, основну концепцію, один компроміс, одну розглянуту альтернативу і одне нерозв’ язане питання. Сфокусуйтеся на мові: використовуйте фрази з цього повідомлення, пишіть активним голосом і будьте точними щодо мови, якою ви хочете писати.

Назва походить від мови індіанців — ненаціональних мов

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

Однією з ключових областей є використання умовної мови. Замість того, щоб сказати «Ми повинні зробити X», що може звучати вимогливо, формулювання його як «Було б корисно дослідити X» або «Розглядаючи Y, ми повинні дослідити, чи може X це вирішити» вводить ступінь дипломатії і запрошує до співпраці. Аналогічно, при описі потенційних недоліків, уникайте тупих тверджень на кшталт «Це розірве все». Замість цього використовуйте такі фрази, як «Потенційні наслідки включають…» або «Ми повинні ретельно оцінити сумісність з…», а потім конкретні зауваження, наприклад, «…і переконатися, що це не вводить регресії в компоненті Z.» Метою є конструктивно оформити обговорення, продемонструвавши, що ви продумали потенційні наслідки.

Інша поширена пастка полягає в виборі дієслова і рівні формальності. Хоча випадковий тон може бути прийнятним у внутрішніх каналах Slack, RFC вимагає більш підвищеного реєстру. Фрази на кшталт «Погляньмо на це» ідеально підходять для швидкої мозкової атаки, але не мають ваги, необхідної для виправдання значних змін в архітектурі. Замість цього скористайтеся такими фразами, як « Ми пропонуємо оцінити…» або « Докладний аналіз показує…», ці фрази демонструють ретельне обмірковування і професійну прихильність. Крім того, будьте обережні з надмірним використанням скорочень - “це”, “ми” і т.д. - у формальному письмі може звучати менш гладко. Стрімтеся до повних речень, де це можливо, щоб підсилити ясність.

Нарешті, пам’ятайте про важливість явного вираження припущень. Технічні обговорення багаті немовленими розуміннями, але RFC * повинні * чітко викладати будь-які основні припущення. Наприклад, замість простого повідомлення « API буде версійно керовано », додайте: « Ми припускаємо, що буде використано схему версійно- сумісного зворотнього зв’ язку, що дозволить безперервну інтеграцію з існуючими системами ». Цей активний підхід зменшує ризик неправильного тлумачення і сприяє більшій гармонії у команді. Недавнє повідомлення Slack від колеги підкреслило це досконало: «Просто хотів позначити, що припущення, що всі клієнти підтримують HTTP / 2, може бути оптимістичним - давайте додамо застереження про потенційні резервні механізми»