change-documentation-guide.md
active
Edit Selected
# Change Documentation Guide
This note explains how change documentation should be created in the homelab documentation repository.
It is the human-readable companion to:
- `notes/ai-change-documentation-spec.md`
## Goal
Whenever we make a meaningful change in the homelab, we want two things to happen:
1. The current-state documentation should reflect the new reality.
2. The change itself should be recorded so we know what happened, why, and what to watch later.
## What Counts As A Meaningful Change
Examples:
- hostname changes
- DNS record changes
- SSH access changes
- onboarding a host
- changing the control node
- modifying storage layout
- moving a service
- changing automation or publish workflow
## What Should Usually Be Created
For most significant changes, create:
1. A dated change note
2. Any current-state documentation updates
3. Any needed policy or runbook updates
## Recommended Structure
### Current state
Use `outputs/current/...` for documentation that describes what exists right now.
Examples:
- current host inventory
- current DNS behavior
- current SSH access model
- current service mappings
### Change history
Use `outputs/history/...` for dated change notes.
Examples:
- `2026-03-18-hostname-standardization.md`
- `2026-03-18-windows-ssh-dns-setup.md`
### Standards and procedures
Use `docs/policies/...` and `docs/runbooks/...` for repeatable guidance.
Examples:
- hostname standard
- SSH access standard
- how to rename a host
- how to add DNS records
## What To Record In A Change Note
Each change note should answer:
- what changed
- why it changed
- which systems were affected
- what files/configuration were touched
- how the result was validated
- what follow-up remains
## Secret Safety
Do not record:
- passwords
- tokens
- private keys
- raw secret files
Do record:
- where secrets are stored
- which systems depend on them
- which config files or env files reference them
## Current Homelab Naming And Access Assumptions
At the time this guide was written, the intended operating model is:
- internal host A records live in `accursedbinkie.com`
- short-name access depends on clients using `accursedbinkie.com` as a DNS suffix/search domain
- `svc-admin` is the default admin SSH identity across the homelab
- `Binkie-Desktop` uses `Jason` as the normal user SSH path
- `Binkie-Desktop` admin access is `svc-admin`
- Windows `svc-admin` SSH access is intentionally limited to trusted homelab systems
## Intended Use With AI
When asking an AI model to document a change, point it to:
- `notes/ai-change-documentation-spec.md`
That file is the instruction document.
This file is the operator-facing summary of the same approach.
---
**Created:** 2026-03-18 22:08:31 UTC