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!

  • Synapse@lemmy.worldEnglish
    18·
    9 days ago
    • 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

    • D_Air1@lemmy.mlEnglish
      2·
      8 days ago

      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.

  • shrek_is_love@lemmy.mlEnglish
    10·
    9 days ago

    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
    • captcha_incorrect@lemmy.worldEnglish
      1·
      8 days ago

      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.

      • shrek_is_love@lemmy.mlEnglish
        2·
        8 days ago

        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 -m which is a bit restrictive in terms of how much you can fit in commit messages)

        • captcha_incorrect@lemmy.worldEnglish
          1·
          4 days ago

          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.

          • shrek_is_love@lemmy.mlEnglish
            1·
            4 days ago

            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)

            • captcha_incorrect@lemmy.worldEnglish
              1·
              2 days ago

              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.

  • tobz619@lemmy.worldEnglish
    6·
    9 days ago

    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.

      • Shimitar@downonthestreet.euEnglish
        3·
        9 days ago

        Thanks you, it means a lot. Just to be clear for whomever didn’t go there: there is zero monetization, no ads, no profiling.

    • BruisedMoose@piefed.socialOPEnglish
      1·
      9 days ago

      Yeah, I’m currently using Wiki.js. I will definitely check out how you’ve got things organized. It looks really good!

      • Shimitar@downonthestreet.euEnglish
        1·
        8 days ago

        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.

    • eli@lemmy.worldEnglish
      1·
      8 days ago

      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.

  • Agent641@lemmy.worldEnglish
    6·
    9 days ago

    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.

  • lightnsfw@reddthat.comEnglish
    4·
    8 days ago

    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.

  • Foster Hangdaan@lemmy.hangdaan.comEnglish
    3·
    9 days ago

    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.

  • DetachablePianist@lemmy.mlEnglish
    3·
    9 days ago

    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.

  • dogs0n@sh.itjust.worksEnglish
    3·
    8 days ago

    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.

  • otacon239@lemmy.worldEnglish
    3·
    9 days ago

    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.

  • irmadlad@lemmy.worldEnglish
    3·
    9 days ago
    • 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)