Private documentation helps me operate the exact system. Public documentation explains the lesson without publishing the map.
“Document the homelab” sounds like one task.
I ended up needing two kinds of documentation because the audiences need different things.
Private operational notes need enough detail to recover the environment under pressure. Public field notes need enough context to teach the decision without exposing the environment.
Trying to make one document serve both jobs weakens both.
Private notes optimize for recovery
When a service fails, I need exact answers.
The private record may include:
- System roles and internal names
- Network and management addresses
- Exact storage exports and mount points
- Service accounts and numeric identities
- Backup locations and recovery order
- Certificate and domain dependencies
- Configuration repository paths
- Links to protected credential systems
That information belongs behind appropriate access controls. Removing it would make the recovery document less useful.
The document also needs an owner, a review trigger, and a known location. A perfect runbook that I cannot find during an outage is not operational documentation.
Public notes optimize for transferable understanding
A reader does not need my internal naming scheme to understand why an application host should verify a network mount before starting a container.
Role names are better:
- Application host
- Storage host
- Management network
- Household clients
- External user
Those labels make the architecture reusable and reduce the chance that several harmless-looking facts combine into a detailed map of my environment.
Public notes can remain technically specific about failure behavior, decision criteria, and validation. Specificity does not require identifiers.
For example, I can explain that a missing remote mount may leave an empty local directory behind. I do not need to publish the real server name, export path, address, or application involved to make that lesson useful.
Sanitization is more than deleting passwords
Credentials are the obvious secrets, but operational exposure is usually cumulative.
A hostname, a private address, a screenshot of a dashboard, a directory containing a username, and a description of an externally reachable service may each look harmless alone. Together they can reveal much more than the article needed to teach.
Before publishing, I look for:
- Internal and public hostnames
- IP addresses and subnet details
- Real domain records and origin endpoints
- Account names, email addresses, and user paths
- API keys, tokens, cookies, and QR codes
- Backup destinations and recovery secrets
- Device identifiers, serial numbers, and MAC addresses
- Exact firewall rules that expose the surrounding architecture
The goal is not to make the article vague. The goal is to replace identifying details with roles, safe examples, and diagrams that preserve the technical truth.
Screenshots need their own review
Text is easier to search than pixels, which makes screenshots deceptively risky.
I review the entire frame, including:
- Browser tabs and history suggestions
- Address bars and bookmarks
- Device labels and account avatars
- Notification previews
- Serial numbers and barcodes
- Wireless names and client lists
- Terminal prompts and working directories
- Background windows and second-monitor content
Cropping is often safer than blurring because blurred text can remain partially readable. A purpose-built diagram is safer still when the live interface adds no essential evidence.
This is one reason the definitive guides use sanitized diagrams instead of screenshots from the live environment. The diagram can show the dependency or traffic flow without quietly publishing the inventory behind it.
The two documents should point to the same truth
Sanitization should change identifiers, not the architecture.
If the private record says storage is remote, the public article should not imply it is local merely to simplify the story. If recovery is untested, the public note should not describe it as proven. If an administrative service is intentionally private, the article should not suggest that exposing it is part of the design.
I maintain the private source first, then derive the public explanation from it. That direction reduces the risk of an article becoming the only place where an important decision was recorded.
The public article becomes a durable explanation of the reasoning. The private runbook remains the source for operating the actual environment.
Documentation decay affects both audiences
Private notes become dangerous when paths, accounts, or recovery steps change. Public notes become misleading when software behavior or supported versions change.
I record what should trigger a review:
- A host migration
- A storage or mount change
- A major application upgrade
- An authentication or remote-access change
- A backup redesign
- A failed recovery attempt
- A public article that reveals an assumption the private notes no longer support
Not every document needs a calendar reminder, but every important one needs a reason to be revisited.
What I would do differently
I would have separated the audiences from the beginning.
Earlier notes alternated between being too vague for recovery and too detailed for publication. The two-layer approach removed that compromise.
It also made the writing better. Once I stopped trying to preserve every implementation detail, the public articles could focus on the decisions, tradeoffs, failure modes, and validation steps that another person could actually reuse.
The rule I use now
Before I publish a technical detail, I ask two questions:
- Does the reader need this detail to understand or reproduce the lesson?
- Does publishing it expose something about the real environment that should remain private?
When the second answer is yes, I replace the detail rather than weakening the explanation.
Private documentation helps me operate the exact system. Public documentation explains the lesson without publishing the map.
Related articles
AI transparency
AI assisted with organizing and editing this article. The two-audience model, sanitization process, and screenshot-review checklist come from documenting, publishing, and reviewing my own homelab and technical articles.