why i keep a private homelab docs repo

the homelab tutorials on this site didn’t start as tutorials. they started as notes to a future version of me who was absolutely going to forget how any of this worked in six months.

that future version of me was right to worry. i’d already caught myself trusting an old note over the actual running config more than once — a device name that had changed, a menu path that had moved between versions, a “cluster” that turned out to be two independent boxes because i’d documented an assumption instead of a checked fact. infrastructure drifts. docs go stale. the box in front of you is the only thing that’s actually telling the truth.

writing for future me, not for an audience

so the real docs live in a private repo. hardware inventory, exact IPs, vlan tables, the specific menu path in the specific version of the software i’m running right now. none of that is written to be read by anyone else — it’s written to be trusted by me, at 11pm, mid-troubleshoot, when i don’t have the patience to reverse-engineer my own past decisions.

writing for an audience of one changes what you bother to record. i don’t explain why vlans exist in that repo. i don’t build up context. i just write down what’s true right now, and update it the moment it stops being true. an architecture decision record for “why an unmanaged switch first” exists because future me will ask that question, not because anyone else needs convincing.

sanitizing it, on purpose, after the fact

the public guides are a second pass. strip the ips, generalize the hardware, keep the actual reasoning — the part that’s useful to someone else even without my specific network in front of them. the private version has “here’s exactly what’s plugged into what.” the public version has “here’s why you’d structure it this way, and where it can go wrong.”

that split is deliberate. a guide that includes my actual IP addressing scheme is a guide that’s harder to reuse and a mildly bad idea to publish. genericizing it forces me to separate “what i happened to do” from “what’s actually the reusable idea,” which is usually a better exercise than it sounds like.

the part i didn’t expect

going back through old private notes to write the public version is where i catch the most drift. writing something down for someone else forces a level of “is this still actually true” that writing a quick note to myself doesn’t. the sanitization pass is accidentally a verification pass.

so the private repo isn’t really overhead on top of the public guides. it’s the thing that makes them accurate.