Short answer
#Why this is better than wrong documentation
It does not feel that way, so it is worth being specific.
A system with a confident, out-of-date architecture document costs you the same discovery work plus the time spent trusting it, plus the decisions taken on the strength of it, plus the moment somebody finds the discrepancy and now distrusts everything else in it too.
A system with nothing costs you the discovery work, and nothing else. You start from a correct model of your own knowledge, which is: none. That is an unusually clean place to build from.
The one thing to be careful of
"No documentation" often turns out to mean "no documentation anybody mentioned". A README from 2021, a wiki nobody has opened, comments at the top of three files, an onboarding email in somebody's archive. Find them — and then treat every one as a declaration to be checked rather than as a fact.
#The first week
-
Day one — what runs, and whose accounts is it in
Which environments exist, what is deployed to each, and for every account the system needs: whose identity is it registered to, who is billed, where do the recovery contacts point.
Ownership problems are cheapest to raise in week one and most expensive to discover in month eight. Do this before anything technical.
-
Day one — take an independent copy of the data
A backup you hold, in a place nobody else controls, that you have personally opened. Everything else on this list can be repeated later; this is the one that protects you from the worst case.
-
Day two — derive the inventory
Components, dependencies, interfaces, data flows, what runs on a schedule. Anybody who can check out the repository can produce this; it does not need somebody who understands the system, which is fortunate.
-
Day three — the outside edges
External services it calls, interfaces it exposes, and who outside the company might be relying on any of them. Cross-check the technical list against the invoices: anything on one and not the other is a question.
-
Day four — write down what nobody can answer
Prioritised, with reasons. This list is the deliverable of the week. It converts “we do not understand our own system” into eleven specific questions, four of which matter.
-
Day five — prove you can operate it
Run it locally. Deploy something trivial. Restore the backup you took on day one into a scratch environment. Each of these either works or gives you something concrete to fix.
#What to read instead of documentation
A system without documentation is still full of evidence about itself.
| Source | What it tells you |
|---|---|
| Commit history | Which files change together, which areas are volatile, who worked on what, and occasionally why |
| Pull requests and issues | The reasoning that never made it into a document. Often the single richest source |
| Tests | Intent. Where they disagree with the code, something interesting happened |
| Invoices | A rough map of external dependencies, from a completely independent direction |
| Cloud console | Everything that exists and is not in the repository |
| Error tracker | What actually breaks, how often, and in which component |
| Support tickets | What users do that the system handles badly. A view no engineer has |
| Deployment logs | Who has deployed, how often, and whether anybody outside one person ever has |
The first two are consistently underrated. A four-year commit history and a few hundred pull requests contain a substantial part of the reasoning that a documentation project would have tried to reconstruct from memory.
#Finding anybody who knows anything
"Nobody to ask" is often "nobody obvious to ask". Worth trying, in this order:
- The commit history. Who wrote the risky parts? Are any of them reachable? A twenty-minute call with somebody who left two years ago can be worth a week.
- Support and operations. People who have handled tickets against this system for years know things no engineer wrote down.
- The finance person. They know which suppliers are paid for, which is the most reliable external-dependency list in the company.
- The suppliers themselves. A payment provider or hosting company can tell you what account exists and who set it up.
- Long-serving non-technical staff. They know what the system used to do, what broke last year, and what everybody works around.
#What to write down, and where
The failure mode of this whole exercise is that the understanding ends up in one new person's head — which is the original problem with a fresh name on it.
Three things worth keeping, and they are small:
- The inventory and the dependencies, derived rather than typed, and refreshed when something material changes.
- The open-questions list, shrinking, with the answer and who gave it recorded next to each closed one.
- A short decisions file — a paragraph each time somebody establishes something non-obvious. Dated, attributed, in the repository.
#What goes wrong
Starting by reading the code.
Instead Start with what runs, in whose accounts, and an independent copy of the data. None of that requires understanding anything.
Writing the documentation that is missing.
Instead Derive the structural half; write only the decisions, as you establish them. A documentation project here is unbounded and will not finish.
Fixing things you find along the way.
Instead Write them down and keep going. Changing a system you do not understand is how the discovery week becomes an incident week.
Keeping it all in your own head.
Instead Everything goes somewhere the company can read. Otherwise you have become the new single point of failure.
Assuming nobody knows anything.
Instead Check the commit history, the support team and the invoices before concluding that. There is almost always somebody.
#What this does not cover
What this does not do
- Deciding whether to keep, rewrite or replace the system. Do the week first; the decision looks different afterwards.
- Hiring. Whether you need somebody permanent for this is a separate question.
- Security review. Establishing what a system is made of is an input to that, not a substitute.
- Anything about the commercial or legal position you inherited along with the software.