Like soup-to-nuts. I know I need to document what I’m doing and I’ve started several times, but then I never go back and make updates. I don’t know if it’s just the ADHD or if I’m just going about it or thinking about it in the wrong way.
So I’m curious about:
- what you use for your documentation
- how you organize it
- what information you include
- how you work documentation into your changes/tinkering flow
Edit: Dang, folks! You all have given me a lot to read through, think about, and explore. Thank you!
You must log in or register to comment.
That’s the neat part, I don’t.
The theory is I use Docmost. The reality is I don’t, and I hope my backups are solid.
“I don’t need to, I have it stored all in my head.”
Famous last words.
It’s not like anyone needs to support it when I’m gone.
I just think I do that, but absolutely don’t.
The fun thing about infrastructure as code is that the terraform, ansible and k8s manifests are documentation.
I only really need to document some bootstrap things in case of emergency and maybe some “architectural” things. I use joplin for that (and many other things).
I used to try and do it all in obsidian but I’d forget a lot. Now I use nix and it’s all done for me basically
- I use Obsidian
- Usually, what I do is write the documentation as I am engaged with the project at hand. Then clean everything up, and transfer to Obsidian.
- I include everything. I don’t leave anything for my mind to wonder about. If I didn’t write it down, it didn’t happen.
- Date any addenda or changes (4-2-26: Firewall rules review)
I’m just rewriting everything in Ansible and I think is worth the effort, it’s self-documented and as an added bonus I won’t have to keep backups of the whole VMs, just the ZFS pool with the data/databases.
NixOS because it’s declarative kind of does it all for me.
The .nix files serve as their own documentation and if I need to do anything outside them I add a comment to the .nix file.
Acronyms, initialisms, abbreviations, contractions, and other phrases which expand to something larger, that I’ve seen in this thread:
Fewer Letters More Letters Git Popular version control system, primarily for code IP Internet Protocol SSH Secure Shell for remote terminal access SSO Single Sign-On VPN Virtual Private Network ZFS Solaris/Linux filesystem focusing on data integrity k8s Kubernetes container management package
7 acronyms in this thread; the most compressed thread commented on today has 17 acronyms.
[Thread #207 for this comm, first seen 2nd Apr 2026, 12:40] [FAQ] [Full list] [Contact] [Source code]
It is hard, if even possible, to keep documentation up-to-date. Better use a configuration management system (salt, ansible etc.) for your servers. Yes, you need to learn how to use it. Yes, it will take a longer time to make changes in your configuration. But as a result you’ll have a self-documented configuration-as-a-code that will allow you to scale your setup as you need. Reproducing something won’t require reading your notes, remembering your actions etc.
But as a result you’ll have a self-documented configuration-as-a-code that will allow you to scale your setup as you need. Reproducing something won’t require reading your notes, remembering your actions etc.
Until you realise that
- you don’t really need to scale a homelab that much
- if something breaks, you just want to quickly fix it manually because “doing the Ansible” is more of a pain
- now idempotency and documentation-as-code is out of the window. ;)
(I’m being tongue-in-cheek here. I don’t doubt this may work for you, but it takes much more discipline than I have.)
you don’t really need to scale a homelab that much
Maybe. But you never know this beforehand.
if something breaks, you just want to quickly fix it manually because “doing the Ansible” is more of a pain
In most cases you just need to replay a playbook for quick fix. But I agree that the proper fix will likely take a longer time (while downtime is much shorter).
now idempotency and documentation-as-code is out of the window.
Let @BruisedMoose@piefed.social decide.
P. S. I don’t like Ansible, other tools can be easier to use. But I don’t want to recommend something concrete.
I don’t like Ansible, other tools can be easier to use. But I don’t want to recommend something concrete.
Which ones do you like to work with? (Even though it’s not a recommendation ;) I’ve only dabbled in Ansible so far and found it overkill for most of the things I do, but maybe one of yours isn’t?
I didn’t try many of them. I use Ansible for my job, but sometimes I hate it. I would try Terraform/OpenTofu or Salt if I were looking for alternative.
All my computers (including servers) share the same NixOS Flake. So my documentation consists of:
- The Nix code itself
- The commit messages for each change I make
- Inline comments in the Nix code
- A few readme.md files to explain the contents of certain directories
In only have one server with NixOS. I don’t use flakes, just plain nix files. It still works great as documentation.
The only thing it is missing is why something is setup in a certain way.
Do you use git? That basically forces you to do some documentation as you go. Multi-line commit messages are often helpful too. (When I first learned git, I only committed using
git commit -mwhich is a bit restrictive in terms of how much you can fit in commit messages)Where do you push to? I have some secrets in my nix files (passwords). While I will get around to move them away from my nix files soonTM, I don’t want to push those to a public repo.
I currently push to a private GitHub repository (planning on moving to a self-hosted Forgejo instance soon).
Although making my nix configuration public would be safe anyway since I use sops-nix which encrypts all my passwords in the repo using a key derived from my SSH key. During nixos-rebuild it decrypts them and puts them each in their own text file at
/run/secrets, with permissions set so you need sudo to view them. (The permissions can be tweaked as needed)It was a pain in the neck to get started with initially (like NixOS itself), but it was very much worth it. (Basically a necessity since putting secrets even in a private repo is considered bad practice)
I was considering putting the secrets somewhere not in /etc/nixos/ and just point to them. Then I could push my nix files without worry. My plan was to use my other server as a remote with just git and ssh, but that server is not responding and is ~6 by car away from me (I don’t own a car). It will be traveling here soon so I can configure it and send it back though.
Thanks for the link to sops-nix, I will check it out. As you said, NixOS is great when you have it running. I can’t see myself going back to debian now.
A great question. First of all, all of my services run with docker compose and use volumes for their config storage which get backed up regularly. Then I just use markdown files organized by having a separate file for each service. Basically anything I would need to reproduce my setup on a new machine is what I try to write down. All the docs and compose yaml files are versioned in git. I usually realize I left out info later on and add it as it occurs to me, typically if I have to set up the services on a new machine. This all applies to any software that needs more than a little config, not just apps hosted for the purpose of other machines using them. It’s a very imperfect process, but it’s a ton better than what I used to do which was think “eh I’ll remember how it’s setup”. I rarely would remember all the key details.
I write everything in text editor first, apply later.
- emacs + org-roam
- by using descriptive names for articles and tags
- everything at the start, trim it down later
