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 # to comment.
That’s the neat part, I don’t.
“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 can remember that” is my cue to write it down, because I won’t.
That’s the devil talking Bobby Boucher.
The theory is I use Docmost. The reality is I don’t, and I hope my backups are solid.
I have an obsidian document where I write changes I want to do in the future that I never look at; does that count?
I just found my todo list and half of it is irrelevant and half of it is done.
I even had a work todo list for my old job lol.
Ouh! I have a checklist of things I need to add/update too, that I never check. Maybe we could mutualize! ;)
I just think I do that, but absolutely don’t.
write-only memory.
no read, only write!
Yeah I also use config-as-code along with wiki but I used to remember things 10 years ago when the setup was simpler and the brain was newer. 😅
I read the title and this was literally the first thing that popped in my head
I’m here to serve.
- what you use for your documentation
Markdown files
- how you organize it
What ?
- what information you include
The commands that worked and the stuff that didn’t work and the links to the source of information
- how you work documentation into your changes
I write as I go. I keep it as part of a git repository when relevant
Had to scroll down this far just to get to markdown files. Although I write with a bit of a delay. Once I get something working. Then I document what worked and what didn’t. Alternative methods and issues I had with the alternatives.
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.
README.mdREADME_I_AAM_VERY_IMPORTANT.md
BTW, this gent’s wiki is worth a bookmark. Stumbled on it before I knew the originator.
Thanks you, it means a lot. Just to be clear for whomever didn’t go there: there is zero monetization, no ads, no profiling.
Yeah, I’m currently using Wiki.js. I will definitely check out how you’ve got things organized. It looks really good!
I am using wiki. Is for a different project and I can’t say I really prefer it over dokuwiki. They both have good points. I don’t like the php dependency of dokuwiki but wikijs feels a bit overcomplex.
Using Mediawiki here.
I have obsidian and tried using it, but my personal workflow for my homelab just doesn’t…work with it? Idk, it’s just easier to throw it into a private wiki.
I still use obsidian but for personal life stuff.
Look’s great, thanks
- 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 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
Why do you have to be like that? Drop the innocent questions and just come right out and call me a piece of shit directly.
Trust me, this is all about me being incompetent.
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.
draw.io in my nextcloud
And leantime to keep track of what I want to do with notes and such
And a mess of notes in Joplin.
I have a bare minimum of documentation as markdown files which I take care to keep in an accessible lovation, aka not on my server.
If my server does ever go down, I might really want to access the (admittedly limited) documentation for it
The moment you think you might possibly need documentation is the moment you should seriously consider using Ansible or similar to orchestra things. Sure, it’s annoying for a single server, but it is the best form of documentation there is.
I use Guix
