Writing RFC and ADR Documents in English
Як написати технічно точні RFC і Architecture Decision Records, використовуючи мову зобов'язань RFC 2119, словник формальної структури і професійну прозу.
RFC (Request for Comments) і ADR (Architecture Decision Record) є двома з найбільш важливих документів, які пише інженер. Їх читають люди, яких ви ніколи не зустрінете, їх цитують у майбутніх рішеннях, і іноді вони розглядаються як обов’язкові контракти між командами. Зрозуміти англійську правильно - це не просто питання стилю - неправильний вибір слів може ввести справжню неоднозначність, яка через місяці викликає справжні проблеми.
Цей посібник містить інформацію про певні мовні шаблони, які роблять RFC і ADR професійними, однозначними і корисними.
RFC 2119: Стандарт мови обмеження
Коли інженери пишуть специфікації і проектні документи, вони часто повинні розрізняти між тим, що система повинна робити, що вона повинна робити, і що вона може робити. RFC 2119, опублікований Internet Engineering Task Force в 1997 році, визначає точний словник для цього. Правильне використання сигналізує про технічний професіоналізм і виключає неоднозначність.
Ключові терміни:
| Term | Meaning | Usage |
|---|---|---|
| MUST / REQUIRED / SHALL | Absolute requirement — no flexibility | ”The service MUST validate the JWT signature before processing the request.” |
| MUST NOT / SHALL NOT | Absolute prohibition | ”The client MUST NOT retry a request with a 400 response code.” |
| SHOULD / RECOMMENDED | Strong preference; deviations allowed with justification | ”Implementations SHOULD use exponential backoff when retrying.” |
| SHOULD NOT / NOT RECOMMENDED | Strong preference against; allowed with justification | ”The API SHOULD NOT return internal stack traces to the caller.” |
| MAY / OPTIONAL | Genuinely optional — acceptable either way | ”Clients MAY cache responses for up to 60 seconds.” |
** Договорення: ** Написайте ці ключові слова великими літерами, якщо ви маєте на увазі значення RFC 2119. Цей знак свідчить читачеві про те, що ви використовуєте ці терміни у технічному сенсі, а не у повсякденному.
** Чого слід уникати: ** Використання « should » (малими літерами), коли ви маєте на увазі « must », створює приховані вимоги. « Служба повинна перевіряти введення » звучить як рекомендація. « Служба МІСТЬ перевіряти введення » є вимогою. Вони мають абсолютно різні наслідки для реалізації і аудиту.
Структура і словник RFC
Добре структурований RFC містить передбачувані розділи. Ось шаблон мови для кожного з них.
Заголовок і резюме
Заголовок повинен бути конкретним: «Пропозиція: Міграція обмеження швидкості до спільного пристрою» краще, ніж «Повнішнє покращення обмеження швидкості»
Резюме або резюме повинно відповідати на одне питання в двох-чотирьох реченнях: що ви пропонуєте і чому?
- “Цей документ пропонує замінити реалізацію обмеження швидкості на послугу спільним проксі-сервером Envoy sidecar. Мотивацією є виключення дублюючої логіки в 14 службах, зменшення конфігурації дрейфу і вмикання централізованого управління обмеженнями швидкості»
Motivation
Цей розділ відповідає на питання «чому?». Використовувати просту причинно- наслідкову мову:
- «Мотивація для цієї зміни — це…»
- «Теперішній підхід має наступні недоліки…»
- «Ця пропозиція керується…»
- Проблема, яку ми вирішуємо, це..
Приклад: «Мотивацією для цієї зміни є непослідовне застосування обмежень швидкості по всіх сервісах. Три служби в даний час не мають обмеження швидкості взагалі, а реалізації, які існують, використовують різні алгоритми і схеми налаштування, що робить аудит політики непрактичним»
Проектування та розробка
Це технічний ядра. Використання:
- «Пропонований варіант — це…»
- “За цією схемою, [компонент] буде [поведінка].”
- «Потік для типового запиту буде таким чином…»
- Цей підхід відрізняється від поточної реалізації в тому, що…”
Будьте конкретними щодо поведінки системи, а не лише щодо її призначення. « Sidecar перехопить всі вхідні HTTP- запити » краще, ніж « sidecar оброблятиме запити »
Розглядаються альтернативні варіанти
Цей розділ важливий і часто написано погано. Ціль полягає в тому, щоб показати, що ви думаєте рішуче, а не швидко відкидати альтернативи.
- Ми розглянули три альтернативи цьому підходу
- “Альтернатива А: [опис]. Це було відхилено, тому що…»
- «Альтернатива B була б простішою для реалізації, але вона не відповідає вимогам аудиту»
- «Ми також оцінювали [інструмент/підхід], але виявили, що…»
Уникайте: « Альтернатива А була розглянута, але не обрана ». Надавайте читачеві достатньо інформації, щоб зрозуміти аргументацію.
Відкритий доступ / Відкритий доступ
- «Наступні питання залишаються відкритими і будуть вирішені до їх реалізації…»
- «Ця пропозиція не розглядає [тему] — це буде розглянуто в окремому RFC.»
- «Наступні винятки явно виходять за рамки цієї пропозиції…»
Структура і лексика мови
Архитектурні записи рішень є коротшими і більш фокусованими, ніж RFC. Вони документують одне архітектурне рішення: що було вирішено, чому і які наслідки. Стандартний формат має п’ ять розділів.
Стан
Один з: Пропонований, Прийнятий, Застарілий, Замінений на ADR-042.
- Процитовано 2012-04-12. (англ.)
- «Статус: замінено на 1977 — «Перехід на інші мови»»
Контекст
Опишете ситуацію, яка змусила прийняти рішення. Використовувати нейтральну, фактичну мову:
- « Зараз програма зберігає дані сеансу в Redis. Оскільки ми масштабуємо до декількох регіонів, потреба в послідовному зберіганні сеансів у регіонах стала блокуючим фактором для проекту гео-розподілу»
- “Ми повинні вибрати брокера повідомлень для нової архітектури, керованої подією. Це рішення впливає на всі служби, які виробляють або споживають події. “
Решение
Визначте рішення чітко і прямо. Почніть з рішення, а потім обґрунтуйте його:
- «Ми приймемо Apache Kafka як основний брокер повідомлень»
- «Ми вирішили використовувати PostgreSQL для первинного сховище даних, а не базу даних документів.»
- Команда погодилася дотримуватися шаблону Hexagonal Architecture для всіх нових сервісів
Уникайте пасивних конструкцій, які затьмарюють значення: « Було вирішено, що буде використано Kafka » слабше за « Ми використаємо Kafka ». У разі ADR важливо знати, хто вирішив, що робити.
Наслідки
Це місце, де багато ADR занадто тонкі. Розділ « Добрі наслідки » охоплює як позитивні, так і негативні наслідки:
- «Це рішення призводить до більш сильних гарантій послідовності для даних сеансу за рахунок збільшення операційної складності»
- «Командам потрібно буде вивчити модель виробник/ споживач Кафки. Ми забезпечимо спільну клієнтську бібліотеку, щоб зменшити криву навчання»
- “Цей вибір створює залежність від доступності Кафки. Ми приймаємо цей компроміс, тому що [причина]»
- Майбутнім службам не потрібно буде приймати це рішення самостійно — стандарт встановлено»
5-й. Обґрунтування (необов’ язкове, але рекомендується)
Поясніть, чому альтернатив було недостатньо:
- «Ми оцінили RabbitMQ і AWS SQS. RabbitMQ надає достатню пропускну здатність, але не має семантики повторення, заснованої на журналі, яка потрібна для сліду аудиту. SQS створить блокування продавця, що суперечить нашій стратегії мульти-хмар»
Реєстрація та реєстрація
Як RFC, так і ADR повинні бути написані формальною, але не бюрократичною англійською. Деякі рекомендації:
** Використовуйте активний голос для прийняття рішень і вимог: **
- « Служба перевіряє токени », а не « Токени перевіряються службою. »
** Використовуйте простий теперішній час для поведінки: **
- «The load balancer distributes traffic across healthy instances.» (англійською)
- Кожен під виставляє кінцеву точку
/healthz
** Використовуйте майбутній час для запропонованих змін: **
- Нова архітектура буде маршрутизувати весь трафік через API-шлюз
- Команди будуть відповідальні за підтримку своїх власних каталогів ADR
** Уникайте хеджування у вимогах. ** Якщо ви написали « службі може знадобитися перевірити токен », ви створили неоднозначність. Промовте « служба МІСТИТЬ перевірити токен » або поясніть умови, за яких перевірка не обов’ язкова.
Поширені помилки
** Смешивание должна и должна: ** Это одна из самых последствий ошибки. Якщо рецензенти ставляться до SHOULD як до MUST, вони будуть надмірно інженерувати. Якщо вони ставляться до МУЖЛИВОСТІ як до ПОТРЕБИ, вони будуть недореалізовані.
** Пасивні розділи з мотивацією: ** « Було спостерігалося, що… » і « Було відзначено, що… » зменшують кількість слів без додавання ясності. Скажи, що ти спостерігав і хто це спостерігав.
Альтернативи, які не є справжніми альтернативами: “Ми не можемо нічого зробити” рідко є справжньою альтернативою. Список параметрів, які були серйозно оцінені, а не просто « солом’ яними людьми ».
** Наслідки, які є тільки позитивними: ** Реальні архітектурні рішення мають компроміси. АДР, що має тільки позитивні наслідки, виглядає, ніби його не продумали.
Писання хороших RFC і ADR є навичкою, яка складається. Кожен документ, який ви пишете, змушує вас думати точно, і ця точність — як технічна, так і лінгвістична — переноситься на кожну іншу форму письмового спілкування у вашій інженерній кар’єрі.