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
You must log in or register to comment.
I’m surprised no one else has answered mediawiki. Love my mediawiki instance.
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.
I just think I do that, but absolutely don’t.
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.
README.mdREADME_I_AAM_VERY_IMPORTANT.md
That’s the neat part, I don’t.
“I don’t need to, I have it stored all in my head.”
Famous last words.
“I can remember that” is my cue to write it down, because I won’t.
It’s not like anyone needs to support it when I’m gone.
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 run Adguard Home containers (the primary auto-syncs to the secondary) and use redirect filters to assign hostnames to each of my containers. I have a “services” folder of bookmarks for each container host so I don’t have to remember each service’s port number. I use KeePassXC to track all my passwords and certificates so authentication is a breeze (someday I’ll get around to setting up an SSO solution). I also keep a .txt file with my basic network info that doesn’t always translate well to dns hostname redirects in adguard. I occassionally remember to update my hosts listed in the file. My individual config files aren’t backed up beyond my automated container backups, but so far none of my services have been that complicated I couldn’t just rebuild from scratch.
It’s not perfect, but combined with my automated backups I have barely enough to rebuild if/when my hardware fails.
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).
That’s the direction I’m moving my lab in. Plus a bit of supplemental markdown to keep track of which guides I’m referencing (and which parts can be ignored because I baked it into the terrafom). It’s really nice to know that as long as I tweak the terraform for changes, I don’t have to worry about forgetting what I changed.
Without really knowing much about it, I just always figured it was overkill for me. Plus I don’t know that I’d even consider myself much more of a beginner with Docker. But you all are making me consider looking into it.
I get that - it’s difficult to see the point in it until you’ve gone along without it. Especially as a beginner since you don’t have a strong sense of what problems you will encounter and how these tools solve those problems.
At some point the learning curve for IaaC becomes worth the investment. I actually pushed off learning k8s myself for some time because it was “too complicated” and docker-compose worked just fine for me. And now that I’ve spent time learning it I converted over very quickly and wouldn’t go back… It’s much easier to maintain, monitor and setup new services now.
Depending on your environment something like Ansible might be a good place to start. You can begin even with just a simple playbook that does an “apt update && apt upgrade” on all your systems. And then start using it to push out standard configurations, install software, create users, etc. The benefit pays off in time. For example - recently (yesterday) I was able to install Apache Alloy on a half-dozen systems trivially because I have a set of Ansible scripts that manage my systems. Literally took 10 mins. All servers have the app installed, running, and using the same configuration. And I can modify that configuration across all those systems just as easily. It’s very powerful and reduces “drift” where some systems are configured incorrectly and over time you forget “which one the correct one?” For me the “correct one” is the one in source control.
Yep. It feels good knowing I can take a few hundred KB of text files and rebuild my whole system.
This is the way
Gitlab has Draw.IO integration, as does Wiki.JS.
- 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
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
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.
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
what you use for your documentation
Hugo (markdown) files that i host on my internal server.
how you organize it
I use basic directory structure. Top level directories are like “dev”, “home”, “general”. Self hosting is a dev/ subdir.
what information you include
Depends on how familiar i am with it and how often I’ll be referencing it. Something i know well or access often will be more high level. Things like an annual process i have documented in more detail
how you work documentation into your changes/tinkering flow
My site has an “edit this page” feature which i use to open my IDE and make the change as I’m doing things. Sometimes I’ll be lazy and just add in what i did this time and then let future me reconcile the differences 🙃
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.
I use Obsidian with a folder for hardware and a folder for software, then an entry for each device or service. I’ve been pretty good about maintaining cross-links.
I kind of wish I used Docker Compose more, but I haven’t run into a situation where it’s been a problem yet.
