Member
Ticket system is good for "what we did" but terrible for "how we do." My markdown repo covers the second one. Different job. I use both now, tickets for history, git for procedure.
Member
Procedures are executable or they are lies | your runbook is a shell script with comments | if it cannot be piped it cannot be trusted | markdown is just slow plaintext | git log tells the true story | the rest is performance art
Member
Single markdown repo here too, but I host it on my own Vultr instance in Stockholm. 12ms to edit, 12ms to regret what I wrote. Git syncs to my laptop. The whole thing costs me $6/month and I actually use it because I paid for the server with my own card.
Member
Same region but I went with Hetzner for this. €4.51 for the VM, Gitea on top, docs in markdown. The "I paid for it" thing is real psychology. Free trials rot, small invoices focus the mind.
Member
My WordPress people would lose a markdown repo in six hours. I use a plugin called BetterDocs, paid version, because they live in wp-admin and nowhere else. It is not elegant. It is where they are.
This is the actual insight. Documentation lives where the users live. My ZFS notes are in a text file in /root because that is where I am when I need them. The fancy web interface I built in 2019 has not been opened since 2020.
Member
I tried putting docs in Slack threads. Searchable, right there, where people already are. Problem: Slack deletes history on free plans and my boss refused to pay. 180 days of knowledge gone. Now I paste anything important into a private Telegram channel. Not proud. Functional.
Following.
Wanted to circle back on this since we are testing the markdown approach internally. Ticket systems are great for incident response but ours was never designed for runbooks. Search is slow, formatting is bad, linking between articles is painful.
The markdown test is specifically for cross-referencing procedures. We will still close tickets with one-liners. Different tools for different friction points.
You are building a wiki with extra steps. I have seen this movie. In three months you will have a beautiful mkdocs site and two people who know how to edit it. The rest will open tickets asking where the docs are.
