Documentation is often treated as something written after the migration. In a legacy modernisation, it is one of the tools that makes the migration possible.
Write down the invisible contracts
The most valuable documentation is not a list of classes. It explains things a new developer cannot infer safely from a view or controller:
- middleware ordering;
- configuration precedence;
- database-provider differences;
- authentication callback state;
- role and session assumptions;
- deployment and recovery behaviour;
- why a compatibility workaround exists.
These are the places where an apparently harmless change can break the system.
Use a layered documentation model
A useful structure has three layers:
- A short README that tells a newcomer where to start.
- Architecture and subsystem guides that explain system-wide flow.
- Source comments that explain local decisions and ordering constraints.
Historical incident notes remain valuable, but they should be labelled as historical rather than competing with the current guide.
Documentation should link to code
Guides should link to the key source files. Code comments should link back to the guide when the explanation spans multiple components. Avoid hard-coded line numbers; link to a file or symbol and let version control show the change.
Documentation is a review aid
A design decision is easier to review when it states the problem, options, chosen approach, trade-off, and retirement condition. That record also helps future developers distinguish intentional compatibility from accidental debt.
The lesson
During a migration, documentation is not ceremony. It is shared memory. It reduces the number of assumptions one person has to carry and makes the next change safer than the last.