There are adherents to TDD who believe that the test is the document for the change.
There are also people who believe that valuable software happens if you just focus on the code.
I am not saying those overlap in a perfect circle, but you should draw your own conclusions.
For the rest of us, we want to document changes for others, without becoming a warehouse of documentation that no one reads.
There are many sources of documentation, and each has its purpose.
There’s PR/MR (Pull/Merge Request) documentation, that documents why you made the changes in your branch, what reviewers and testers should be concerned about, and areas you believe need extra attention.
There’s the documentation you put into a user story / ticket; where you want to capture the relevant details of why you’re doing this story; the ins and outs with other parts of the system; the high level details that this story encompasses; and the desired end state.
There’s the documentation you put into code: the code comments where you explain why you did what you did in an area where you couldn’t use proper naming to disclose your thinking. There’s also the tests you write, whether they’re characterization tests to detail how the component works and why it works that way, or the contract test that details what your APIs expect and how they work, or a end-to-end test that details the path the user takes through the system, that ties a user action to the actions the system takes to carry out that user request. There are also development driven by tests; that detail the particular ranges and expectations for each line of code.
But, none of these documents explain why a system is changing to a particular implementation, or new technology, or changing from an event-sourced system to a transactional system, or why angular was chosen over react (or vice versa), or how that affects the business, or how the business affects system changes.
Think about all the factors that go into any large change in a system:
- Political context (there’s a possible re-org, and you want to show value before that happens so you don’t get re-organized right out the door)
- Team context (the team doesn’t really understand the Reactive programming pattern, and so implementing RxJS or NGRX will take too much time, or the people on the team just don’t like to write unit tests)
- Financial context (we have three weeks budgeted to fixing this part of the system)
- Business context (there’s a sales deadline in two months, so whatever we have has to be done in one month so sales can meet their quotas with this new feature)
- Technical context (We can’t upgrade to .NET Core because of legacy library X, so we have to remove/replace that library before we upgrade to .NET core, and that upgrade requires a new license agreement that has to go through procurement)
- Architectural context (Our system is required to produce reports within 5 minutes of a transaction happening, so any solution needs to fit in to that architectural standard)
They may be uncomfortable to capture, but you need to capture them, because in 6 months you’re not going to remember why you made the decision you did, or all the ins-and-outs that caused that decision, but you need to, because if you don’t you might reverse course in 6 months only to lose both ground and faith from your business stakeholders.
You capture these decisions in what is known Architectural Decision Record; a document that contains all of those contexts I listed above; and for each record, you should fill out each section, even if it feels uncomfortable to do so. If you say, “well, this section is going to be blank so I’ll skip it”, then think hard about that context before skipping it. There’s always a business factor at play, or a social factor at play; it just may be uncomfortable to talk about; or it may be “because we want to maintain the status quo politically”, but it’s there.
They are also good to have listed because they give you areas to ask stakeholders about. Asking your boss, what political considerations are involved? is a necessary (albeit uncomfortable) question, because you want to do the right thing that gets the right result; and politics is how two or more people make decisions. Asking your manager about the financial considerations is just as crucial; because if you don’t ask, you’ll get surprised when you only have three weeks when you thought you had six (BTDT).
Besides those contexts that are each of their own sections, there are also other sections for the ADR:
1. Change desired
2. Reason for Change
3. Contexts (from above)
4. Approach A
– Pros
– Cons
– impacts on those contexts and considerations
5. Approach B
– Pros
-Cons
– Impacts
6. Approach C
– Pros
– Cons
– Impacts
7. Approaches that didn’t make the top 3 but were discussed (you can bullet these, don’t need to go into detail)
8. Decision
9. Follow-up date on this decision and the follow-up recorded impact
This is the template I use; there are others, and you should mix and match your ADRs to fit your business. The most crucial part I’ve found is the actual context around the decision, because those are meant to capture the aura around a potential change; and that’s usually the first casualty of memory.
I pick three approaches because there’s research that says you should offer choice, but not too much; and if you can’t find yourself a third choice, remember: doing nothing is also an option.
These documents sometimes take weeks to fill out; that’s OK. The important part is that they take as long or as short as needed to capture the decision and receive alignment from others as to why the decision is being made. That will vary on the team and the change needed, but is one way to align the team to move nimbly, not just quickly.