Як писати ADR англійською
Вивчіть структуру і фрази англійської мови для написання запису про рішення щодо архітектури, включаючи контекст, саме рішення і його наслідки.
ADR, який тільки стверджує рішення, є наполовину корисним - цінність архітектурного рішення запису в основному в контексті і наслідках розділів, які дозволяють майбутньому інженеру зрозуміти, чому рішення мало сенс в той час, навіть якщо це виглядає сумнівним через роки.
Ключовий словник
** Контекст ** — розділ, у якому описується ситуація, обмеження і сили, які призвели до прийняття цього рішення, написано так, щоб майбутній читач розумів, яку проблему насправді було вирішено, а не лише те, що було обрано. “Контекстний розділ повинен пояснити, що ми вибирали під жорстким терміном з невеликою командою, не знайомою з Kubernetes - це обмеження має таке ж значення, як і само рішення, коли хтось прочитає це через два роки і запитає, чому ми не вибрали “очевидно кращий” варіант.”
Рішення — конкретний, заявлений вибір документів ADR, написаний однозначно і без хеджування, оскільки ціла суть документа полягає в тому, щоб зафіксувати те, що було фактично вирішено, а не представити варіанти. “Розділ з рішеннями не повинен виглядати як порівняння варіантів — ясно вкажіть, « ми використаємо PostgreSQL як основний сховище даних », а не « ми схиляємося до PostgreSQL, але все ще розглядаємо альтернативи. » ADR записує рішення, а не постійне обговорення. ”
** Наслідки ** — розділ, що документує як позитивні, так і негативні результати, які команда приймає, приймаючи це рішення, включаючи компроміси, від яких свідомо відмовляється, що робить ADR чесним, а не самовдячним. “Розділ наслідків повинен включати недоліки, які ми приймаємо, а не тільки переваги - ми отримуємо простоту операцій, але ми також приймаємо де-факто одну точку невдачі, поки ми не інвестуємо в реплікацію, і цей компроміс повинен бути записаний явно.”
** Стан** — коротке поле, яке вказує, чи було запропоновано, прийнято, відкинуто або замінено пізніше рішення, що дозволяє читачам швидко визначити, чи рішення все ще діє, не читаючи повного документа. “Під час оновлення поля стану введіть « замінено на ADR- 042 », а не вилучайте цей старий ADR — історія того, чому ми змінили напрямок, є цінною, і позначення стану таким чином зберігає цю історію непошкодженою, а не вилучає її.”
Звичайні фрази
- Чи контекстний розділ пояснює фактичні обмеження, або просто передає рішення?»
- Чи рішення оголошено однозначно, чи все ще читається як відкрите порівняння?»
- Чи ми задокументували реальні наслідки, включаючи компроміси, які ми приймаємо?»
- «Що таке ринок цінних паперів і як він працює?» (рос.)
- Чи варто цей ADR позначати як замінений тепер, коли ми прийняли новіше рішення?»
Приклади висловлювань
Запис контекстного розділу:
- “Контекст: час розгортання нашого поточного монолита збільшився до понад 40 хвилин, а команда зросла з 3 до 12 інженерів, які працюють на одній кодовій базі, що спричиняє часті конфлікти злиття і суперечки щодо розгортання. Ми оцінювали, чи інвестувати в монолітні інструменти або почати розділення на послуги. ”*
Я ясно сказав:
- “Рішення: ми витягнемо модуль розрахунків у окрему службу, яка буде спілкуватися з монолитом за допомогою чітко визначеного внутрішнього API, як перший крок поступового розкладання, а не повного переписування.” *
Написання розділу з чесними наслідками: “Наслідки: це негайно зменшує розгортання суперечок для команди розрахунків, але вводить мережеву затримку і новий режим невдачі - відмова служби розрахунків тепер може погіршити поток оплати монолита таким чином, як раніше не могла, і ми приймаємо цю операційну складність.”
Професійні поради
- Написати розділ ** контекст ** для читача, який не має досвіду роботи у залі засідань — включити обмеження і сили, які грають роль, а не лише резюме проблеми.
- Заявляйте про **рішень ** як про чітке, зобов’язане речення, а не порівняння варіантів - ADR записує те, що було вирішено, і належить після дебатів, а не під час них.
- Будь чесним у розділі ** consequences ** про реальні компроміси і прийняті мінуси, а не тільки переваги — розділ наслідків, який перераховує тільки позитивні сторони, не є надійним.
- Зберігайте поле ** стан ** актуальним, оновлюючи його до замінених, а не вилучаючи старі ADR — запис того, як змінювалися рішення, часто є таким же цінним, як і будь- яке окреме рішення.
Практичні вправи
- Напишіть контекстний абзац для гіпотетичного рішення щодо переходу з REST на GraphQL.
- Сформулюйте рішення в одному однозначному реченні.
- Напишіть розділ про наслідки, який включає принаймні один чесний мінус.
Наприклад, слово «навигація» означає «перетворення архітектурних форм»
Будьмо чесними – навіть з чітким розумінням того, що слід писати в АДР, сформулювати ці думки чітко англійською мовою може здатися складним. Це не просто заява фактів; це про передачу намірів і запрошення до співпраці. Погано сформулований ADR може призвести до неправильного тлумачення, переробки і, врешті-решт, марного часу. Давайте зосередимося на вдосконаленні вашого вимови, щоб ваші рішення щодо архітектури були легко зрозумілі і прийняті командою.
Одна з найскладніших областей - це оформлення самого рішення. Замість простого твердження « Ми обирали X », розгляньте такі фрази, як « Щоб зменшити проблеми з продуктивністю у шарі API, ми вирішили перенести доступ до даних на архітектуру мікросервісів ». Зауважте, що вказано контекст — « проблеми з продуктивністю » — і пояснення * чому * було прийнято це рішення. Це змінює фокус від просто результату («X») до основного розуміння. Іншим корисним доповненням є передбачення потенційного відсіку. Фраза на кшталт «Цей підхід вводить операційну складність щодо міжслужбового зв’язку, який ми розглянемо через…» негайно сигналізує про обізнаність і запрошує обговорення про стратегії зменшення ризиків.
Окрім офіційних документів, ADR часто викликають розмови. Подумайте про те, як ви б повідомили про це рішення в каналі Slack. Замість того, щоб просто сказати « Перехід на мікросервіси », спробуйте щось на зразок: « Гей, команда, подумайте про останні проблеми з продуктивністю API — досліджуйте архітектуру мікросервісів як потенційне рішення. Початкові думки стосуються поліпшення масштабованості і від’єднання. Давайте обговоримо плюси і мінуси!» Ключовим тут є те, щоб оформити це як дослідження, а не як указ. Аналогічно, при написанні опису PR, замість «Рефакторинг для мікросервісів», націлюйтеся на «Рефакторинг шару API для прийняття архітектури мікросервісів для вирішення проблем з продуктивністю і поліпшення масштабованості — подальша дискусія добре прийнята»
Нарешті, пам’ятайте, що ADRs по суті є співпрацею. Не бійтеся використовувати неофіційну мову — такі фрази, як «Ми розглядаємо…» або «Потенційна альтернатива є…» сигналізують про відкритість до зворотнього зв’язку. Важливим елементом є активне залучення вкладу: «Які ваші думки про компроміси між цим підходом і [альтернативою]? Чи є якісь невідкладні проблеми, які ви передбачаєте?» Ціль не в тому, щоб наказати рішення, а прийти до нього разом. Освоєння цих нюансів значно поліпшить ефективність ваших ADR і сприятиме більш продуктивному інженерному середовищу.