Документирование решений — Примеры

Пример 1 — Документ, который описывает, а не решает

Команда держит страницу об архитектуре в вики. Ей два года, и она неверна. Новичок спрашивает, почему оформление заказа синхронно вызывает сервис остатков, и никто не может ответить, поэтому замените страницу на то, что действительно помогает.

docs/architecture.md   (последняя правка 2 года назад)
  «в системе три сервиса и общий кэш»

реальность сегодня: пять сервисов, кэш убран, добавлена очередь
вопрос новичка: «почему синхронно, а не через кэшированную копию?»

Решение

docs/decisions/0007-sync-order-lookups.md
контекст:      ценообразованию нужен уровень клиента в момент оформления
варианты:      синхронный вызов (просто, добавляет режим отказа); кэшированная копия (быстро, может быть устаревшей)
решение:       синхронный вызов с тайм-аутом 200 мс и запасным уровнем
последствия:   оформление отказывает в пользу уровня по умолчанию; кэш можно добавить позже

Описание текущей системы устаревает в момент, когда его рисуют, и читателям не хватает не его — код они могут прочитать сами. Восстановить нельзя другое: взвешивание альтернатив, то есть почему этот вызов, а не кэшированная копия и почему эта граница, а не более простая. Запись одного решения, его отвергнутых вариантов и цены отвечает на вопрос новичка абзацем и остаётся полезной годами именно потому, что никогда не претендует описать систему такой, какая она сейчас.

Пример 2 — Запись, тихо отредактированная под реальность

Решение отменено, а исходную запись обновляют, чтобы файл не вводил в заблуждение, и через полгода то же изменение предлагают снова. Объясните, что уничтожила правка, затем покажите, что следовало написать.

docs/decisions/0003-use-redis-for-sessions.md
  исходный текст:  «решение: сессии в Redis»
  правленый текст: «решение: сессии в базе данных»   (файл перезаписан на месте)
  # рассуждения в пользу Redis и в пользу ухода от него исчезли

Решение

0003-use-redis-for-sessions.md              без изменений
0011-sessions-in-the-database.md            вытесняет 0003
  контекст:      Redis добавил зависимость, которую команда не могла сопровождать круглосуточно
  варианты:      управляемый кластер Redis; сессии в основной базе данных
  решение:       сессии в основной базе данных
  последствия:   больше нагрузки на основную базу; не нужно думать об инвалидации кэша

Правка старой записи под сегодняшнюю реальность уничтожает единственное свидетельство того, почему прежний выбор был сделан, — а это обычно и есть важная часть. Новая запись, которая называет своего предшественника, сохраняет оба решения и причину изменения, так что история решений становится объяснением формы системы. Правило дешёвое и абсолютное: никогда не переписывайте запись, даже когда она теперь читается как неверная.