Archive note: A December 30, 2025 inventory described roughly 260
Markdown files. The preserved SoCalNomad documentation tree now contains
about 277 Markdown files totaling roughly 4 MB. The problem was
structure and duplication, not raw disk usage.
Documentation is supposed to reduce the cost of remembering.
Ours had begun to increase it.
The SoCalNomad project accumulated architecture plans, phase reports,
deployment logs, troubleshooting notes, session summaries, success
reports, handoffs, roadmaps, and several generations of files named some
variation of STATUS, RESUME, or
CURRENT.
Each document had been useful when it was written. Together they made
it difficult to answer a basic question: which one describes the system
that exists now?
More Documentation Is
Not More Context
The archive contained valuable evidence. It explained why decisions
had been made and preserved incidents that would otherwise disappear.
Deleting it all would have traded confusion for amnesia.
The failure was allowing historical and operational documents to
occupy the same conceptual layer.
A new contributor or AI assistant could find:
- A design that was proposed but never implemented
- A deployment report for an environment that no longer existed
- A session summary that contradicted a later fix
- A “final” architecture followed by another “final” architecture
- Credentials or identifiers that should never have been copied into
prose
Search results ranked matching words, not truth.
Status Documents Decay
Quickly
Files named STATUS.md feel authoritative, but their
value falls rapidly when they are not maintained. A stale status file is
often worse than no status file because it presents old assumptions as
current facts.
The project needed a small set of explicit document roles:
- Current state: what is verified now
- Operating guide: how to perform recurring work
- Architecture: durable boundaries and rationale
- Decision record: why a consequential choice was
made - Session log: temporary evidence from a work
period - Archive: material retained for history, not
instructions
The role should be visible from location and naming, not inferred
from the prose.
“Final” Is Not a Lifecycle
Many files acquired names such as COMPLETE,
SUCCESS, or FINAL. Those names recorded the
emotional end of a work session rather than the lifecycle of the
system.
Software continued changing. The triumphant document did not.
A better pattern was to date historical records and keep the current
document boring:
docs/current/status.md
docs/current/operations.md
docs/architecture/newsroom.md
docs/decisions/2025-12-26-specialized-desks.md
docs/archive/sessions/2025-12-29-publishing-fix.mdHistory becomes searchable without competing for authority.
Documentation Is Also an
Input Surface
The sprawl became more consequential when AI tools entered the
development process. An assistant could read and summarize documents
quickly, but it could also absorb obsolete instructions quickly.
That made documentation hygiene part of system safety.
An archived file containing an old credential, destructive command,
or retired deployment path was no longer inert. If surfaced without
context, it could influence a current operation.
The cleanup therefore needed more than moving files:
- Remove secrets from historical prose.
- Mark archived documents as non-authoritative.
- Keep one verified status entry point.
- Link current documents to deeper references.
- Prefer small decision records over giant session narratives.
- Periodically test whether a new session can identify the current
state.
The Value of Session Logs
Session logs were not the enemy. Several of the best technical
stories on this blog came directly from them.
They captured failures while the details were still available: the
wrong cluster identifier, fifty-five inconsistent publication records,
model migrations, rate limits, and workflow loops. A polished
architecture document often removes exactly the uncertainty that makes
an incident useful.
The mistake was treating a session log as an operating manual.
Session logs should be immutable evidence. Current guides should
extract the lasting decision and discard transient noise. Blog posts can
later extract the human narrative.
The Test for Useful
Documentation
A documentation system should answer three questions quickly:
- What is true now?
- Why is it built this way?
- Where is the historical evidence?
If one search returns twenty plausible answers to the first question,
the repository has storage but not knowledge management.
The count of Markdown files was memorable, but file count was never
the real problem. A few hundred small documents are manageable when
their authority and lifecycle are clear. Ten contradictory documents are
not.
Documentation becomes a knowledge base only when the reader can
distinguish instruction, rationale, and history.