DOCUMENTATION
> tree --dirsfirst -I 'archive|assets'
The network documentation isn't an afterthought — it's a deliverable. The README alone is a structured reference with a table of contents, navigation guide, and version history. Behind it are 15+ pages organized into four categories, covering everything from hardware configuration to operational runbooks.
The goal is the same one I have for any system I build: if I get hit by a bus, someone else can pick this up and run it. In this case "someone else" is probably future me after not touching it for six months — which is functionally the same problem.
Twilight-Zone-Network/ ├── README.md ← Primary reference (you're reading about it) ├── Missing-Info.md ← Active backlog of gaps to fill │ ├── 01-Configuration/ ← How things are set up │ ├── Hardware-Configuration.md │ ├── Controller-Configuration.md │ ├── Pi-Software-Configuration.md │ ├── Server-Software-Configuration.md │ └── Surveillance-Configuration.md │ ├── 02-Reference/ ← Standards and lookups │ ├── Naming-Conventions.md │ ├── Password-Standards.md │ └── Port-Reference.csv │ ├── 03-Operations/ ← How to do things │ ├── Reboot-Instructions.md │ ├── VPN-Cheatsheet.md │ ├── Security-Cheatsheet.md │ ├── Display-Cheatsheet.md │ ├── Maintenance-Procedures.md │ ├── Monitoring-and-Logging.md │ ├── Backup-Procedures.md │ └── Troubleshooting-Guide.md │ └── 04-Scripts/ ← Automation ├── Script-Guide.md ├── Database/ ├── Pi/ └── Windows/
01-CONFIGURATION
The "what is it and how is it set up" section. Hardware specs, software configuration, controller settings, service parameters. Written so you can rebuild any component from the doc alone.
5 documents covering every major component
02-REFERENCE
Quick-lookup material. The naming convention doc explains the Twilight Zone theme and how to name new devices. Password standards define complexity and rotation. The port reference is a CSV for easy searching.
3 documents — standards that prevent drift
03-OPERATIONS
Runbooks for common tasks. "How do I reboot the Pi safely?" "How do I add a VPN client?" "What do I check during monthly maintenance?" These are the docs that save you at 2am when something breaks and you can't remember the right command sequence.
8 documents — the largest section, by design
04-SCRIPTS
Automation code with documentation. Database maintenance scripts, Pi service management, Windows client utilities. Each script has a guide explaining what it does, when to run it, and what to expect.
Script guide + organized by platform
Version Control
The documentation lives in a Git repository with a changelog in the README. Major architecture changes trigger a version bump. The current version is 5.1, reflecting the migration from a previous gateway platform.
Living Documentation
There's a Missing-Info.md file that tracks documentation gaps — an active backlog of things that need to be written or updated. The docs are never "done," just like the network.
Naming Conventions
A dedicated document defines the naming scheme for every device, VLAN, and service on the network. New components get named following the convention — not whatever seemed clever at the time. Consistency over creativity.
Quarterly Review
The documentation has a defined review cadence. After major architecture changes or quarterly — whichever comes first. This prevents the most common failure mode of documentation: it's accurate on day one and wrong by month three.
This documentation structure mirrors what I build professionally:
| HOME NETWORK | EQUIVALENT AT WORK |
|---|---|
| 01-Configuration | Infrastructure-as-code, environment setup guides |
| 02-Reference | ADRs, coding standards, schema documentation |
| 03-Operations | Runbooks, incident response playbooks, on-call guides |
| 04-Scripts | CI/CD pipelines, migration scripts, automation |
| Missing-Info.md | Documentation debt backlog |
> The tools change. The pattern doesn't.