That’s the neat part, I don’t.

Dokuwiki

wiki.gardiol.org

For me for future memory and for others who might need it

• 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)

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’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.

At work, since I’m the sole IT, I’ve been putting everything into MkDocs and it’s been working out great for the team. Only complaint is that I can’t seem to figure out how to update anything without just relaunching the Docker container every time. They mention that you can live reload, but not how.

• 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 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

Acronyms, initialisms, abbreviations, contractions, and other phrases which expand to something larger, that I’ve seen in this thread:

6 acronyms in this thread; the most compressed thread commented on today has 12 acronyms.

[Thread #207 for this comm, first seen 2nd Apr 2026, 12:40] [FAQ] [Full list] [Contact] [Source code]

I have compose and a justfile, that’s enough documentation for any project, right??

Bookstack in a docker container. You can export pages with revision numbers and dates. I print out the emergency stuff and keep it in a binder. www.bookstackapp.com I’ve been using it at work for like a decade now. No apps or anything though, just a decent web interface.

I write everything in text editor first, apply later. 1. emacs + org-roam 2. by using descriptive names for articles and tags 3. everything at the start, trim it down later

It depends on what it is. I do not have a singular documentation-platform or wiki for those things. I’m more of the keep the docs where the code is guy. I also try to keep complexity to a minimum.

All my linux server setups are done with ansible. ansible itself is pretty self-documenting, as you more or less declare the desired outcome in YAML form and ansible does the rest. This way, I do not need to remember it, but it’s easier to understand when looking it up again.

Most of my projects have a git repository, so most of what I need to know or do is documented

• in a README.md
• as pipeline-instructions inside .gitlab-ci.yml

This way, I was able to reduce complexity and unify my homelab projects.

My current homelab-state is:

• most projects are now docker-based
• most projects have a GitLab CI for automated updating to newer versions
• the CI itself is a project and all my CI-docker-based deploys use this unified pipeline-project
• most projects can be tested locally before rolling out new versions to my VMs
• some projects have a production and a staging server to test
• those which cannot be dockerized or turned into a CI are tools and don’t need that (e.g. ansible playbooks or my GitLab CI)

On what to include, I always try to think: Will I still be able to understand this without documentation if I forget about the project for 6 months and need to make a change then? If you can’t be sure, put it in writing.

If it’s just a small thing regarding not the project itself or the functionality or setup itself but rather something like I had to use this strange code-block here because of XXX, I’ll just put a comment next to the code-line or code-block in question. These comments mostly also include a link to a bug-report if I found one, so i can later check and see if it’s been fixed already.

GitOps with assorted readme files in the repo for various bits.

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.

If you have a mix of different systems both on-prem and cloud, and tie them together in various ways using VPNs, mesh or otherwise, create a graph using something like Excalidraw to give yourself a refresher on how everything connects. You want machines, hostnames, IPs, ports, and a list of services. You don’t have to be fancy by creating visual representations of each service, just a bulleted list. You only really have to update this when adding or removing compute.

If you’re running services on lots of different nodes, a spreadsheet that just maps services to whatever URL you use access them, to whichever backend server is running them. This takes minimum effort and gets you 90% of the way there.

Short: don’t do anything manually, throw it into a ansible playbook. Save it somewhere.

Use declarative systems and software, where the configurations files themselves are the documentation. For example, I use Guix and Podman. The entire OS is described in a Scheme file and all the services are described in a YAML file. I just need those two files to get an overview of the entire setup.

Notesnook notebook with whatever info I need to be able to administrate the system. e.g. what different ports are used for and why the firewall policies are what they are, sometimes write-ups after a troubleshooting session, etc.

The Notesnook instance is self-hosted too, but if the server goes down, the notebook will still be available locally.

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.

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.

All my computers (including servers) share the same NixOS Flake. So my documentation consists of:

1. The Nix code itself
2. The commit messages for each change I make
3. Inline comments in the Nix code
4. A few readme.md files to explain the contents of certain directories

Day job: oneScrote and fucking ansible

Night job: some wiki for the architecture, but just config management for the config detail : we run the docs and it’s done. Thankfully not fucking ansible; because in any environment where there are options, it’s not fucking ansible.

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.

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.

<img alt="" src="https://lemmy.ca/pictrs/image/ef1ed243-a004-46d1-b0d5-90aa284d3daa.jpeg">

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 🙃

I keep everything I do as minimal as possible.

Everything is documented using either sh scripts or markdown style plain text files. If I need anything more than that, I’m over complicating things for my brain.

The upside to this approach is that it works anywhere because it’s all just text files and it’s very tiny in size. I am more interested in making low-power/low-spec things work so less is appropriate.

I don’t have many machines but about 40 containers. I used docker compose. Then I’ve found Trillium Notes for the documenting part. I have the client on my mac that syncs to the trillium container on my server that way I can always have access if something happens and the server is down or I need it offline. One thing I love about it is that I’ve set it so all pages are read only by default. This makes it work for me more like a wiki and I don’t accidentally overwrite something. The discipline to keep it updated?.. biggest challenge.

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

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.

README.md

Gitlab has Draw.IO integration, as does Wiki.JS.

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.

github.com/netbox-community/netbox

draw.io in my nextcloud

<img alt="network diagram on nextcloud" src="https://lemmy.today/pictrs/image/fafadad3-e0ae-42e4-835e-4e58221a9567.png">

And leantime to keep track of what I want to do with notes and such

<img alt="leantime kanban screenshot" src="https://lemmy.today/pictrs/image/fd0adf02-cf38-42e5-8421-66ac1fe4293a.png">

And a mess of notes in Joplin.

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 use Guix

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.