Як написати технічний RFC
Практичний посібник з написання технічних RFC (Request for Comments) англійською мовою — структура, словниковий запас і фрази, за допомогою яких можна отримати схвалення ваших пропозицій.
RFC (Request for Comments) — документ, що пропонує технічну зміну, нову систему або важливе рішення — і запрошує команду переглянути і обговорити його перед початком реалізації. Написання переконливого RFC є як технічною, так і письмовою вмінням. Добре написаний RFC буде схвалено швидше, створить більше корисного зворотнього зв’ язку і створить вашу репутацію інженера, який чітко мислить.
Що робить RFC обов’язковим
Хороший RFC виконує три завдання.
- Ясно пояснює проблему - навіть для когось, хто не знайомий з цією областю
- ** Пропонує конкретне рішення ** — з достатньою кількістю деталей для його оцінки
- ** Чесно визнає компроміси ** — показує, що ви розглядали альтернативи
RFC, які пропускають крок 3, часто не досягають консенсусу, тому що рецензенти підозрюють, що автор не продумав все до кінця.
Стандартна структура RFC
Заголовок і метадані
** RFC- 042: Міграція служби автентифікації до токенів на основі JWT ** ** Стан: ** Чернетка ** Автор: ** [Ваше ім’ я] Створено: 2026-06-13 ** Рецензенти: ** [Імена]
Резюме (2-4 речення)
Запитай це останнє, але поклади першим. Він повинен сказати читачеві, що ви пропонуєте і чому, простою англійською:
*“Ця RFC пропонує перенести нашу поточну автентифікацію на основі сеансу на безстатеві токени JWT. Основною мотивацією є підтримка горизонтального масштабування рівня API без спільного зберігання сеансів. Очікуваним результатом є 40% зменшення навантаження бази даних від сеансових запитів і простіша інфраструктура для багаторегіонального розгортання. * “
Пояснення проблеми
- “Поки що сеанси користувачів зберігаються у Redis і запитуються при кожному автентифікованому запиті. Це створює залежність стану, яка запобігає незалежному масштабуванню серверів API. Оскільки ми готуємось до багаторегіонального розгортання, ця архітектура стає значним обмеженням.”*
Використовуйте теперішній час для опису поточного стану. Будьте конкретними — включайте метричні дані, якщо ви їх маєте.
Пропонований варіант
- “Ми пропонуємо замінити токени сеансу підписаними JWT (JSON Web Tokens). Токен буде видано під час входу до системи, у ньому міститиметься ІД користувача і роль, а також буде підписано за допомогою закритих ключів RS256. Токени закінчуються через 15 хвилин; токени оновлення з 7-денним терміном дії дозволять безшумну повторну автентифікацію без необхідності повторного входу користувача в систему.”*
Розбивати складні пропозиції на пронумеровані кроки або підрозділи. Використовуйте діаграми, де вони пояснюють (посилайтеся на них як «див. рисунок 1»).
Розглядаються альтернативні варіанти
Цей розділ демонструє інтелектуальну чесність:
“Ми розглянули три альтернативи, перш ніж прийти до цієї пропозиції:”
*“**Параметри А — Зберегти поточний сеанс, але перейти до розподіленого кешу. *Це зменшить затримку, але не вирішить фундаментальну проблему стану для багаторегіонального розгортання.”
*“*Параметри B — Використовувати непрозорі токени з централізованою службою перевірки токенів. ** Цей варіант уникає вбудовування даних користувача у токени, але вводить нову залежність від служби для кожного автентифікованого запиту.”
- “*Параметр C (запропоновано) — JWTs без стану. ** Виключає залежність від сховища сеансів, уможливлює горизонтальне масштабування і є стандартом у галузі. Компроміс полягає в тому, що токени не можуть бути негайно відкликані без додаткового механізму блокування списку. “
Ризики та ризики
- “Складність відкликання токена: На відміну від токенів сеансу, JWT не можна анульувати до закінчення терміну дії. Ми зменшимо це, використовуючи короткий час закінчення терміну дії (15 хвилин) і підтримуючи блоковий список для високоризичних подій, таких як зміна пароля і припинення облікового запису. ”*
- ”** Поворот ключа: ** Якщо ключ підпису буде порушено, всі токени стануть недійсними одночасно. Ми реалізуємо автоматизовану ротацію ключів з 90-денним циклом.»*
План дій
- “Фаза 1 (2 тижні): Впровадження видання і перевірки JWT у службі автентифікації. Розгорнути за функціональним прапором.”*
- “Фаза 2 (1 тиждень): Міграція внутрішніх служб для перевірки JWT. Вилучити залежність від сховища сеансів.”*
- “Фаза 3 (процес триває): моніторинг частоти помилок і затримки. Видалити прапорець можливості.”*
Мова для опису мов RFC
Пропоную:
- “Ми пропонуємо… / Цей RFC пропонує… / Рекомендований підхід…” *
Пояснення аргументів:
- “Перша мотивація… / Причина такого підходу… / Це краще, тому що…” *
Відповідь на питання:
- “Головним недоліком є… / Одним з обмежень цього підходу є… / Це не стосується X, який буде оброблено окремо.” *
** Запит на відгук: **
- “Звернення особливо добре приймаються щодо… / Ми не впевнені щодо… / Внесок команди безпеки був би тут корисним.” *
Поширені помилки RFC
- ** Занадто нечітке: ** « Ми повинні поліпшити систему автентифікації. » — це не пропозиція, це бажання.
- ** Без альтернатив: ** Пропуск цього розділу змушує переглядачів відчувати себе маніпуляторами.
- ** Немає критеріїв успіху: ** Як ви дізнаєтеся, чи спрацювали зміни? Додати вимірювані результати.
- ** Занадто довгий: ** Документ RFC не є технічною специфікацією. Намагайтеся мати 800-1500 слів. Посилання на специфікації у додатках.
Добре написаний RFC є одним з найважливіших документів, які може створити інженер. Вона вирівнює команди перед початком роботи, рано виявляє проблеми і створює постійний запис того, чому були прийняті рішення. Вкладайте час, щоб написати його добре.
Національна мова: мова, що використовується в технічній літературі
Написання переконливого технічного RFC - особливо, коли ви не повністю володієте англійською - може здатися пригнічуючим. Легко впасти в шаблони, які не повністю передають ваші ідеї або, гірше, створюють непорозуміння. Будьмо чесними, тиск на представлення складних технічних деталей, одночасно борючись з незнайомими словниковим запасом і структурами речень, є значним. Поширеною проблемою, яку ми бачимо, є те, що розробники використовують надто спрощену фразу - іноді ненавмисно - тому що вони намагаються зменшити неоднозначність, але це може насправді зробити речі * більш * заплутаними для рецензентів, які очікують певного рівня точності і формальності.
Однією з ключових областей, на якій варто зосередитися, є ясність через активний голос і точні дієслова. Замість того, щоб сказати «Було спостерігалося, що…», спробуйте «Ми помітили, що…». Це змінює акцент з пасивного спостереження на розуміння вашої команди і запропоноване рішення. Аналогічно, заміна неясних термінів, таких як «це» або «це» з конкретними посиланнями - наприклад, посилаючись на певний номер питання або назву компонента - значно покращує розуміння. Під час перегляду коду ви можете отримати коментар на зразок: « Чи можете ви розкрити причину цієї зміни? » Хороша відповідь — це не просто « Це працює ». Це може бути: « Ми спостерігали збільшення затримки у сценарії X, і ця рефакторизація оптимізує потік даних за допомогою [особливого алгоритму/ методу], як описано у документі Y. Метою є скорочення середнього часу відповіді приблизно на 15%, як це виміряно за допомогою наших внутрішніх еталонів.” Бачите, як це більш конкретно і чітко сформулює * чому *?
Іншою частою проблемою для носіїв мови, які не є рідними, є розуміння очікувань щодо формальності в технічній документації. RFC не є випадковими розмовами у Slack; вони вимагають професійного тону. Фрази на кшталт «Я думаю» або «може ми могли б…» зазвичай уникаються, замінюються більш упевненими заявами на кшталт «Ця конструкція адресує…» або «Ми пропонуємо реалізувати…». Під час створення описів PR, уникайте надмірно непрямої мови. Замість того, щоб сказати: « Можливо, цей підхід буде корисним », ясно скажіть: « Впровадження цієї оптимізації покращить продуктивність на X% ». Нарешті, завжди двічі перевіряйте свою граматику і правопис – такі інструменти, як Grammarly, можуть бути безцінними, але не покладайтеся виключно на них; свіжа пара очей (ідеально, хтось знайомий з проектом) є ключовою для виявлення тонких помилок.