В процесі розробки модуля аналітики ми ухвалюємо безліч рішень, котрі стосуються того, в який спосіб ми інтерпретуємо дані, або ж які елементи даних ми використовуємо для певних потреб, або ж в який спосіб ми презентуємо ці дані.
Ці рішення можуть бути задокументовані у різноманітних дискусіях у Slack, у нотатках зустрічей, або ж у задачах чи обговореннях на GitHub. Або ж вони можуть бути незадокументовані взагалі, а лише проговорені усно.
За таких умов може бути складно відтворити власну аргументацію щодо якогось рішення ("а чому ми беремо географію з даних обʼєкта?", "а як ми визначаємо, чи стосується тендер будівництва?"). Тим більше може бути складно комунікувати це для нових людей у команді або ж для зовнішніх партнерів.
Рішення
Визначити перелік важливих рішень, ухвалених нами в процесі роботи над модулем аналітики, та для кожного рішення підготувати architectural decision record.
An architecture decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
An architecture decision (AD) is a software design choice that addresses a significant requirement.
An architecture decision log (ADL) is the collection of all ADRs created and maintained for a particular project (or organization).
An architecturally-significant requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture.
Яким є статус цього рішення - запропоноване, ухвалене, відхилене, архівоване, замінене.
Контекст
Яку проблему ми вирішуємо? Що стимулює нас до ухвалення цього рішення чи запровадження змін?
Рішення
Які альтернативи, варіанти рішення ми розглядаємо? Яке рішення ми пропонуємо, або ж які зміни ми запроваджуємо? Чому саме це рішення? Якими є його переваги та недоліки?
Наслідки
Що змінюється внаслідок ухвалення цього рішення? Які речі стають простішими, а які складнішими? Яких елементів стосується це рішення?
Інструментарій, середовище для запису
Здебільшого технічні команди записують ADR у markdown (один запис - один файл), та підтримують репозиторії із записами. Для деяких форматів навіть існують спеціальні утиліти командного рядка. Втім, оскільки наші записи можуть знадобитися не лише технічним командам, ми можемо почати з простого варіанту - підтримки журналу записів у Google Docs.
В такому разі на першій сторінці ми можемо тримати шаблон запису. Для створення нового запису потрібно буде скопіювати шаблон на нову сторінку та модифікувати його.
Потреба
В процесі розробки модуля аналітики ми ухвалюємо безліч рішень, котрі стосуються того, в який спосіб ми інтерпретуємо дані, або ж які елементи даних ми використовуємо для певних потреб, або ж в який спосіб ми презентуємо ці дані.
Ці рішення можуть бути задокументовані у різноманітних дискусіях у Slack, у нотатках зустрічей, або ж у задачах чи обговореннях на GitHub. Або ж вони можуть бути незадокументовані взагалі, а лише проговорені усно.
За таких умов може бути складно відтворити власну аргументацію щодо якогось рішення ("а чому ми беремо географію з даних обʼєкта?", "а як ми визначаємо, чи стосується тендер будівництва?"). Тим більше може бути складно комунікувати це для нових людей у команді або ж для зовнішніх партнерів.
Рішення
Визначити перелік важливих рішень, ухвалених нами в процесі роботи над модулем аналітики, та для кожного рішення підготувати architectural decision record.
Формат запису
Існує декілька форматів запису ADR, але ми можемо скористатися найпростішим з них - Decision record template by Michael Nygard.
Інструментарій, середовище для запису
Здебільшого технічні команди записують ADR у markdown (один запис - один файл), та підтримують репозиторії із записами. Для деяких форматів навіть існують спеціальні утиліти командного рядка. Втім, оскільки наші записи можуть знадобитися не лише технічним командам, ми можемо почати з простого варіанту - підтримки журналу записів у Google Docs.
В такому разі на першій сторінці ми можемо тримати шаблон запису. Для створення нового запису потрібно буде скопіювати шаблон на нову сторінку та модифікувати його.