Architecture Decision Record

Active theme: Light

← документи

Поради щодо написання якісних ADR

Ознаки якісного ADR:

  • Обґрунтування: поясніть причини ухвалення саме цього AD. Це можуть бути контекст (див. нижче), плюси й мінуси різних можливих варіантів, порівняння можливостей, обговорення витрат і вигод тощо.

  • Конкретність: кожен ADR має стосуватися одного AD, а не кількох.

  • Позначки часу: вказуйте, коли написано кожен пункт ADR. Це особливо важливо для аспектів, що можуть змінюватися з часом, як-от витрати, графіки, масштабування тощо.

  • Незмінність: не змінюйте наявну інформацію в ADR. Натомість доповнюйте ADR новою інформацією або замінюйте його, створивши новий ADR.

Ознаки доброго розділу «Контекст» в ADR:

  • Поясніть ситуацію вашої організації та її бізнес-пріоритети.

  • Додайте обґрунтування та міркування, засновані на соціальному складі й навичках ваших команд.

  • Додайте релевантні плюси й мінуси та опишіть їх у термінах, що відповідають вашим потребам і цілям.

Ознаки доброго розділу «Наслідки» в ADR:

  • Поясніть, що випливає з ухвалення рішення. Це можуть бути ефекти, підсумки, результати, подальші дії тощо.

  • Додайте інформацію про будь-які наступні ADR. Досить часто один ADR породжує потребу в нових ADR, наприклад, коли один ADR робить великий загальний вибір, який своєю чергою створює потребу в додаткових менших рішеннях.

  • Додайте будь-які процеси ретроспективного огляду. Типово команди переглядають кожен ADR за місяць, щоб порівняти інформацію в ADR із тим, що сталося на практиці, і так навчатися та зростати.

Новий ADR може замінити попередній ADR:

  • Коли ухвалюється AD, що замінює або скасовує попередній ADR, слід створити новий ADR