Why I Document Every System I Build (And the Template I Use)
I have a rule: no system goes to production without a one-page document. Not a 50-page design doc. Not a Confluence wiki that nobody reads. One page.
The Template
```markdown
[System Name]
What It Does (2 sentences max)
[Plain English description of what this system does and who uses it.]
Architecture
[ASCII diagram or link to Excalidraw/Mermaid diagram]
How to Run Locally
[3-5 commands. Copy-paste should work.]
How to Deploy
[1-2 sentences. Usually "push to main."]
How to Monitor
[Where are the logs? What dashboard to check? What alerts exist?]
Key Dependencies
[External services this depends on. What happens when each one is down?]
Known Limitations
[What this system explicitly does NOT do. What edge cases are unhandled?]
Contact
[Who built this? Who maintains it? Where to ask questions?] ```
Why One Page
Because nobody reads longer documents. I've written 20-page design docs that were read by 2 people (me and the reviewer who skimmed it). I've written 1-page docs that were read by 15 people and referenced monthly.
Brevity forces clarity. If you can't explain your system in one page, you don't understand it well enough.
The Sections That Matter Most
"Key Dependencies" is the most valuable section.
```markdown
Key Dependencies
| Dependency | What Happens When It's Down |
|---|---|
| Supabase | Dashboard shows cached data. New data stops. Auth still works (JWT cached). |
| Stripe | Payments queue. Users retain access. Webhook backlog processes on recovery. |
| GitHub API | Telemetry dashboard degrades to Snapshot mode. No data loss. |
| Alpaca API | Price alerts stop. Dashboard shows last known prices. |
| ``` |
When production is on fire at 2am, this table tells you exactly what to expect. No guessing, no source code diving, no Slack archeology.
"Known Limitations" is the most honest section.
```markdown
Known Limitations
- Does NOT handle concurrent edits to the same strategy. Last write wins.
- Price alerts have ~2 second latency due to polling (not WebSocket).
- Historical data only goes back 5 years (yfinance limitation).
- Max 50 active alerts per user (Redis memory constraint). ```
This prevents the "but I assumed it could handle X" conversation. Every limitation is a feature request that was intentionally deferred, not forgotten.
When I Write the Doc
I write the document BEFORE I write the code. Not after. Before.
The document is my first draft of the architecture. Writing "this depends on Supabase and degrades to cached data when it's down" forces me to DESIGN the degradation behavior before I build it.
Without the document, I'd build the happy path first and "add error handling later." The document makes "later" happen now.
The Documents I Maintain
Every system in the Nexural ecosystem has one:
| System | Doc | Last Updated |
|---|---|---|
| Trading Dashboard | `docs/trading-dashboard.md` | This week |
| Discord Bot | `docs/discord-bot.md` | This month |
| Alert System | `docs/alert-system.md` | This month |
| Quality Telemetry | `docs/telemetry.md` | This week |
| Research Engine | `docs/research.md` | Last month |
Total time maintaining 5 documents: about 2 hours per month. Time saved by having them: immeasurable.
The Career Signal
When I interview, I mention that I document every system I build. The reaction from hiring managers is always the same: relief.
They've been burned by engineers who built systems that nobody else could understand. Documentation isn't glamorous, but it's the difference between a system that survives your departure and one that doesn't.
If you can build it AND document it AND hand it off — you're not just an engineer. You're a professional.