Migration documents often describe the destination in impressive detail while saying very little about the journey. Months later, the team can see the new architecture but cannot explain why an awkward dependency remains. I now write those decisions down while their context is still fresh.
Record the reason alongside the choice
A useful decision record describes the constraint, the alternatives considered, and the evidence that would make us reconsider. It is short enough to update when reality changes. Diagrams help with structure, but the surrounding explanation preserves the reasoning that a diagram cannot show.
Documentation is most valuable when it makes a future decision easier.
During a migration I attach these records to the work they explain and review them at each handover. That keeps documentation close to the people using it. The result is less polished than a large final report, but much more likely to remain useful.