Here’s my approach to documentation. It’s about habits as much as it’s about actually writing anything down:

1. Never setup anything important via naked terminal commands that you will forget you did

2. Always wrap important commands in some kind of “setup-xyz.sh” script and then run that script to see if your install worked.

3. If you need to make a change to your service, ensure you update your script and so it can be re-run without braking anything

Get into the habit of this and you are documenting as you go

Every time I set up anything, I do one of two things:

• If it’s container based, it gets a commented docker compose file in my custom orchestration

• If it’s on a host system, the changes are scripted and commented in a setup script, which are run on new machines. If the acrit is specific to one machine, it is configured as such

I find in-setup docs to be best for a home lab, plus if I have to replace hardware, it’s fast.

Fun fact, I do it for laptops and desktops, too.

I don’t, and I know that I’m fucked one day.

The whole deployment is done via ansible, so the ansible source is my documentation.

I use the notes sections in proxmox preeettty heavily. Lots of links to the helper scripts, youtube videos and other resources i used to get er’ goin’.

In the near future I’m really hoping I can set up Netbox to help me document the network and equipment I’m putting in my homelab. a nice thing is that I went through a divorce a while ago and I’m getting to start from scratch. You’d be surprised at just how much you’ve learned since starting to self host and I think there’s this sunk cost fallacy that gets a lot of us to keep going with what we’ve got already set up because we’ve “already put so much work into it” and the concern of what we might lose by scrapping it and starting over.

Also, not what you asked… but if you’re still relatively new with proxmox you should check out the ProxmoxVE helper scripts. Lots of good automated scripts from doing a post-install to setting up various LXC containers and VM’s

I keep a very rudimentary README.md with some basic info on the services I run. I should probably set up a personal wiki to keep track of everything better

Perhaps more importantly, I also maintain a document with all the scheduled tasks that run, including what it is, how it’s defined, when it runs, and what device runs it. Really helpful for making sure cron jobs don’t run during a backup script or something

I just set up everything via ansible and comment everything religiously, I’ve gotten to the point where I have playbooks for my laptop and desktop so if I have do do a clean install I just have to run the playbook and everything is set up and installed to my liking

It’s annoying to go to my playbook to make changes and rerun it every time I want to install or remove anything from my daily PCs, but it pays off when I migrate computers or for some reason have to do a clean install

And for high level stuff and things not in ansible I keep a tiddlywiki since no matter how catastrophic the failure of my systems I can always find a way to access an HTML file for my own reference

I am fortunate enough to only manage a homelab and not an enterprise sized network. So I don’t document anything just like at work.

I refused to do any documentation for a long time because it made me feel stupid for not memorizing it. I learned it the hard way… Now I document everything possible with Git and Readmes.

I use different things:

• Netplan for the actual hard “inventory” like documentation. What cable goes where, what powers what, what MAC is assigned to what, when did I buy this or that?(The later with an addon). In theory I also have snipe-it,but doing it all in netplan is more convenient.

• Wiki.js for the concept and How-To-Side. Lots of draw.io diagrams (which can be done directly in articles), HOWTOs as a reminder for me, naming conventions, etc. Also some basic inventory information for disaster recovery. (Wiki.js is not hosted locally)

• Vaultwarden for all secrets,passwords, recovery keys, ssh keys,etc.

• Gitea for the most important config files/scripts/docker compose files.

• And last but not least I do backups to Mdisc Blue Rays every few months. These include the documentation, the most important files (knx project for example), etc. and are stored at a different location (bank safe). There is also an detailled explanation in both my wifes and my own will how to access these so if something happens the kiddos or someone taking care of them can gain access.

NixOS’s declarative configurations basically document themsleves: add some comments and you’re good to go and can back then up to wherever whenever

Secrets go in Keepass.

For server configs, a LibreOffice Writer file per machine (except for RPs, I only have one for those), written as a didactic manual explaining how to install and configure everything (I work on bare metal still). I started that way since diving into self-hosting was also a way to learn Linux, Sys-Admin and web-hosting. I don’t do anything without updating the relevant chapters, or creating new ones. Not gonna lie: it’s tedious. But also a life-saver, and the rationals for my choices remain available years later, which is priceless in many ways.

Once upon a time I had neat network gear running, and I mostly YOLO-ed the doc for those, relying instead on the firmware/config backups. I had to put those devices away, but when I finally get to play with them again, I’m going to suffer re-learning and re-discovering everything.

Recently, I got to hack and old console, and just did a chronological log-file with actions taken and URLs to guides, instead of writing down everything myself. It got me thinking I might add a simple log-file to track my actions, on top of my usual guides.

Or not. Having a life is nice too 😅

🧠 + a few slapdash notes in a password manager. It’s very organic, very human.

Occasionally leads to situations like this.

The Ansible playbooks I use to deploy it are the documentation.

Lol.