The Historic Decisions Document

Documentation: The Importance of Historic Decisions

"The purpose is not to repeat what can be logged in a doc block, or referred to in a ticket number in a comment, or reviewed in a living design document."

"Don’t expect future-you to understand the context of the present. The Historic Decisions Document is a tool that will make your life easier in the future so you can focus on the important things that matter."

Documentation is a hassle. It forces you to spend extra cycles on overexplaining what you just did. However, there are times when you come across a weird piece of logic that needs clarification. Enter the Historic Decisions Document.

The concept behind this artifact is to record the WHY of features, capturing the reasoning behind decisions that may be forgotten months or even years down the road. It goes beyond what can be logged in a doc block or referred to in a ticket number. Instead, it focuses on the actual decisions made throughout the project's lifecycle.

The Historic Decisions Document serves as an encyclopedia about the project for your team, shedding light on what is changing in the system. This becomes increasingly important as your engineering organization grows. Even in a small organization, it prevents over-reliance on subject matter experts who may not always be readily available.

By creating this document, you are ensuring that future-you and others, both technical and non-technical, can understand the context of the present. It becomes a valuable tool that simplifies your life in the future, allowing you to focus on the important things that matter.