map-an-undocumented-system

Map an undocumented system

A body of documentation that only states what it knows produces a specific, expensive illusion:

Everything not written down is either unimportant or does not exist.

Neither is true. What is not written down is usually the part nobody understood well enough to write. The gaps are not the leftovers of the documentation effort — they are its most actionable output.

So record them. Deliberately, in the repository, with the same care as the facts.

When to use this

• Documenting a system for the first time
• Migrating loose notes into a structured knowledge base
• Onboarding onto something someone else built
• Answering "what do we actually know here?" before a risky change
• Any time you catch yourself writing "presumably" or "I assume this is"

The procedure

1. Give the gaps a home

A list of unknowns kept in your head, or in a session that ends, is not a map. It needs a file that lives with the documentation and is read at the same time.

2. Write each gap as a question, not as a feeling

🔴 If you cannot phrase it as a question with a possible answer, it is not a gap — it is unease. Unease belongs in prose; gaps belong in the list.

Not a gap	A gap
"The networking side is murky"	"Which component terminates inbound connections before they reach the application?"
"Storage worries me"	"What is the retention policy on the archive volume, and who set it?"
"Nobody understands the scheduler"	"What triggers the nightly run, and where is its schedule defined?"

3. Say what the gap blocks

A gap with no consequence attached will never be closed, and should not be. Write the decision that is waiting on it: "blocks: whether this can be restarted during business hours."

Gaps that block nothing go in a low-priority section, or nowhere. A gap list that grows without bound stops being read, which makes it worse than no list.

4. Prove the gap — searching and not finding is the evidence