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.
Ansible.
Infrastructure as code is the best documentation.
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.
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.
When I set something up I write all the steps I’m doing in obsidian as I do it. The pages get tagged so they’re searchable in the future.
ADHD: functional notes in abbreviated version on fat strips of painter’s tape on server case or shelf. Passwords go on page dedicated to that server or service in a little black notebook, then eventually in a password manager.
Readme file if my brain lets me, usually 3 months later after hyperfocus on troubleshooting.
Honestly, the tape idea is one of the most practical ones in the thread!
I just create a README.md file wherever I setup services with docker compose which keeps top level docs so I know how and why certain things work.
Other than that, if comments are supported inside configuration files, also document stuff in there too.
That’s been good enough for me.
I use Guix
I’m actually in the middle of rebuilding my entire setup right now and one of my major goals is to actually document my processes this time.
I use Obsidian which is a Markdown editor and I have a couple plugins alongside that for QoL stuff and extra features.
I document processes, problems and fixes I encounter, list of active services alongside where/how to access them, and plans for future additions/changes.
As far as working documentation into your flow, realistically that is just a matter of discipline. It is explicitly up to you to stay on top of documentation.
Hope that helps, and good luck with your endeavor! 😁
I second Obsidianmd.
Even before adding community plugins, the search, organization, and the ability to easily link to other documents/screenshots make documentation so easy for me
I’m surprised no one else has answered mediawiki. Love my mediawiki instance.
Man I’m as basic as it comes. I have a .txt file that I update with today’s date and write what I’m working on. I try to write as much as needed on what I’m working on. I write commands down and save links to reading material.
It’s not the best but it’s better than nothing.
I use obsidian, I dont really have a self hosted setup yet but thats what I use to document desktop config and what I will use for my server when I get it running.
I was just introduced to NetBox and it’s really intriguing. It does look complicated but once it is setup it seems to work very well at integrating data from a spreadsheet into it and then automatically documenting changes and such. It’s open source as well.
That’s the neat part, I don’t.
“I don’t need to, I have it stored all in my head.”
Famous last words.
Documentation is for onboarding other people. Why on earth would I need to onboard other people to something self-hosted?
Sometimes future me has the memory of a goldfish, and I fear that, for future me, the online sources that guided me before won’t be there for me anymore
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.
