Writing Architecture Decision Records: Advanced Language and Structure
Виходьте за рамки шаблону ADR: освойте досконалу англійську мову контексту, компромісів, наслідків і мови стану, щоб ваші архітектурні записи рішень можна було читати з повагою.
Більшість інженерів знають шаблон ADR — Context, Decision, Consequences. Але знати шаблон - це не те ж саме, що писати ADR, який читає авторитет. Різниця в мові: як ви формулюєте проблему, як ви зважуєте варіанти, не звучачи байдужими, і як ви чесно стверджуєте наслідки. Цей посібник призначено для інженерів, які вже пишуть ADR, але бажають, щоб вони працювали так само, як і ADR старшого архітектора.
Швидке оновлення структури
** Запис рішення щодо архітектури (ADR) ** — це короткий документ, який містить одне важливе рішення: що ви вирішили, чому ви вирішили, і скільки це коштує. Стандартні розділи:
- ** Заголовок ** — короткий, у формі рішення
- ** Стан ** — запропоновано / прийнято / застаріле / замінено
- ** Контекст ** — сили, що грають
- Рішення — те, що ви обрали
- Наслідки - те, що слідує, добро і зло
Решта цього посібника стосується написання кожного розділу мовою, яка є точною і впевненою.
Заголовок: у формі рішення, а не теми
Слабкий заголовок називає * тему *. Сильне заголовок називає * рішення *.
- Слабкий: «Вибір бази даних»
- Strong: «Використовувати PostgreSQL як основний сховище даних»
- Ще сильніше (коли є напруга): «Прийняти PostgreSQL над DynamoDB для транзакційних завантажень»
Використовуйте форму дієслова з наказовим відмінком: Вживати, Прийняти, Мігрувати до, Стандартизувати, Забути. Це така ж граматика, як і у хороших повідомленнях спільного виконання Git — команда, яка описує дію рішення.
Контекст: мова «сил»
Розділ Контекст пояснює * чому це рішення було навіть необхідним *. Найбільш професійні ADRs рамки контексту як набір ** сил ** - конкуруючих тиску, що обмежують вибір.
Корисна мова блокування:
- «Ми обмежені…»
- «Існує **напруга між ** часом до ринку і довгостроковою підтримкою.»
- «Наступні ** сили ** в грі:…»
- Це рішення ** керується ** потребою зменшити операційну нагрузку. ”
- «Наше теперішнє підхід більше не розміри, тому що…»
«Ми зараз запускаємо три окремих кешування шарів, кожен налаштований по-різному. Ця ** фрагментація ** збільшує оперативне навантаження і час набору. Ми обмежені невеликою платформою команди, яка створює тиск для консолідації. ”
Написати Context в теперішньому часі — він описує ситуацію як вона є зараз. Не завантажуйте його рішенням; читач повинен відчути проблему, перш ніж побачити відповідь.
Решение: скажите это, не закрывайте глаза
Розділ «Рішення» є єдиним місцем в технічному письмі, де хеджування є неправильним. Після того, як ви вирішите, перенесемо:
- «Ми приймемо PostgreSQL.»
- «Ми стандартизуємо на одному шарі кешування, використовуючи Redis.»
** До (слабкий): ** “Ми вважаємо, що краще використовувати PostgreSQL, хоча можуть бути причини переглянути це рішення.” ** Після (сильний): ** “Ми приймемо PostgreSQL як основний сховище даних для транзакційних послуг.”
Використовуйте “we will” — теперішнє/майбутнє зобов’язання, активний голос, “ми” як підмет. Зберігайте нюанс для наслідків.
Розглянуті варіанти: вага без вафлі
Сильні АДР включають альтернативи, які ви відкинули, і * чому *. Тут живе мова компромісів:
- Ми розглядали три варіанти: …»
- «Вибір A пропонує X за ціною Y.»
- «Ми виключили DynamoDB, тому що наші шаблони доступу є реляційними.»
- “Решущим фактором була оперативна знайомість.”
- «На балансі, PostgreSQL найкраще задовольняє сили вище.»
Чиста таблиця порівняння виглядає добре:
| Option | Pros | Cons | Verdict |
|---|---|---|---|
| PostgreSQL | Relational, mature, team knows it | Manual sharding at scale | Chosen |
| DynamoDB | Managed, scales automatically | Access patterns don’t fit | Rejected |
| Keep status quo | No migration cost | Fragmentation persists | Rejected |
Словник для висновків: * вибраний, відхилений, відкладений, переглянути пізніше, поза сферою застосування.*
Последствия: будь честен о минусах
Це розділ, який відокремлює зрілі ADR від маркетингу. Перелік як позитивних, так і негативних наслідків. АДР з позитивними сторонами читається як наївний.
Рамка:
- «В результаті, вступ стає простішим.»
- «Компроміс є, що ми беремо на себе відповідальність за вручну шардування понад ~1TB.»
- Це вводить нову операційну залежність
- «Ми приймаємо ризик, що …»
- Це рішення ** обмежує ** майбутні вибори навколо мульти-регіону. ”
“Позитивний: єдиний, добре зрозумілий склад даних зменшує когнітивне навантаження. Негативний: ми приймаємо ручне шардування понад 1 ТБ і втрачаємо автоматичне масштабування DynamoDB. Нейтральний: нам потрібно буде побудувати моніторинг з’єднання-пулу, якого ми не мали раніше.”
Фраза ”** ми приймаємо ризик, що… **” є золотом. Це сигнал того, що ви побачили недоліки і все ж вибрали — ознака навмисного рішення, а не недогляду.
Мова стану і життєвий цикл
ADR незмінні після прийняття — ви не редагуєте їх, ви ** замінюєте ** їх. Словник станів:
- ** Пропонується ** — обговорюється
- ** Прийнято ** — погоджено і вступило в силу
- ** Застаріла ** — більше не рекомендується, але не замінено
- Замінено на ADR-014 — замінено на новіше рішення
Процитовано 2010-09-21. Статус: Замінено ADR-021. Ми перейшли від ручного шардингу до Citus; див. ADR-021 для поточного підходу
Зауваження: * застаріле * і * замінене * не є однією і тією ж річчю. ** Застаріле ** = виходить з ужитку. ** Замінене ** = явно замінено на щось конкретне. Поєднання їх - це поширена помилка.
Список мов і діалектів
- ** Контекст: ** теперішній час (« Ми зараз запускаємо… »)
- Рішення: майбутнє/зобов’язання («Ми приймемо…»)
- Наслідки: теперішній/майбутній («Це вводить…»)
- Голос: переважно активний з «ми» як підметом — це запис людських рішень, тому приймайте їх.
Нерідко твори письменників-неовід’ємних персонажів
- **Захист рішення. ** “Ми можемо використовувати…” підриває весь документ. Прими решение, а потом выполняй.
- ** Перелік тільки переваг. ** Рецензенти довіряють ADR більше, коли вони називають мінуси.
- Редагування прийнятих ADR. Не робіть цього. Написати новий і позначити старий як замінений.
- Плутанина “застаріле” і “замінене”. Використовуйте замінене ADR-X, коли є заміна.
- ** Неясні назви. ** « Кешування » — це тема. « Стандартизація кешування програм на Redis » — це рішення.
Ключевые вещи
- Назвати АСД як ** рішення ** з наказовим дієсловом, а не темою.
- Формуйте Контекст як конкуруючих сил у теперішньому часі — дайте читачеві відчути проблему.
- У Рішенні, викинути всі хеджування: “Ми.”
- Показувати ** розглянуті варіанти ** з чесними компромісами і чітким ** вирішальним фактором **.
- Завжди перераховуйте негативні наслідки і використовуйте “ми приймаємо ризик, що…” — це сигналізує про навмисний вибір.
- Не редагувати прийняті ADR; замінити їх, і зберігати застарілі і замінені окремо.
Навигація Nuance: мова для міжнародних команд
Написання ефективних записів архітектурних рішень (ADR) не просто про документування технічних виборів; це, по суті, вправа на комунікацію. При роботі в різних командах, особливо тих, що поширені в різних лінгвістичних середовищах, тонкі відмінності у фразування можуть суттєво вплинути на розуміння і співпрацю. Основні принципи ясності і точності залишаються найважливішими, але розуміння того, як носії англійської мови інтерпретують певні конструкції, є ключовим для того, щоб ваші АДР були справді доступними і поважаними.
Розглянемо такий сценарій: Ви переглядаєте PR, надісланий колегою з Іспанії. У описі написано: « Ми реалізували нову функцію для поліпшення продуктивності ». Хоча це технічно вірно, у описі бракує контексту. Рідний англомовний користувач може негайно запитати: «Повніше * на скільки *? Які показники ми націлюємось?» або, більш критично, «Які були компроміси, пов’язані з цією оптимізацією - чи вплинула вона на інші області системи?» Оригінальна фраза не запрошує глибшого вивчення, що саме те, що надійний ADR намагається викликати. Аналогічно, в каналі Slack, де обговорюються майбутні зміни в архітектурі з колегами з Німеччини, висловлювання на кшталт «Це буде просто» може бути інтерпретовано дуже по-різному, ніж було заплановано; німецький колега може сприйняти його як відсутність деталей або відверте ставлення до потенційної складності.
Іншою поширеною пасткою є використання надмірно асертивної мови. Фрази на кшталт «Ми * повинні * зробити це» можуть здатися диктаторськими, навіть якщо вони мають добрі наміри. Замість цього, обґрунтування рішень фразами на кшталт «Ми розглядаємо дослідження…» або «Наша поточна гіпотеза є…» дозволяє відкриту дискусію і визнає альтернативні перспективи. Хорошим прикладом в описі PR буде зміна з «Це вирішує ваду» на «Це вирішує повідомлену проблему, реалізовуючи [спеціальне рішення]». Остання чітко говорить * як * вона вирішує проблему, залишаючи менше місця для неоднозначності і спонукаючи рецензентів зосередитися на технічних деталях, а не просто підтверджуючи її існування.
Нарешті, пам’ятайте, що специфічна термінологія, пов’язана з архітектурою - такі терміни, як “масштабованість”, “стійкість” або “технічний борг” - можуть мати різні конотації в різних культурах. Важливо чітко визначити ці терміни в самому АСД, особливо при обговоренні їхніх наслідків. Використання глосарію ключових архітектурних термінів поряд з вашими записами може бути надзвичайно цінним способом, сприяючи спільному розумінню і мінімізуючи потенційні непорозуміння. Створення цього спільного словника є постійним процесом, що заохочує відкритий діалог і забезпечує, що кожен відчуває себе обладнаним, щоб зробити значний внесок у вирішальні архітектурні дискусії.