Rotation works until you hit the person who "forgets" and then the doc rots for a month. Seen it at three places now.
iBGP, eBGP, don't care, just peer
What do you use for documentation that actually gets read?
DANA3
Member
ana_mad said:
We rotate it. One week per person
Same here but we call it "gardening duty". Person also fixes broken links and deletes pages about services we killed two years ago. Terraform docs especially need it because modules change and examples go stale fast.
Bruno22
Member OP
Rotation is good idea! In Brazil we have "plantao" for everything, hospital, police, now documentation haha
But serious, I think my problem is deeper, people here do not believe in documentation. They say "I will remember" or "ask me". How to change this culture?
ping so high I wave back
srelet
Member
You don't change the culture. You change the path of least resistance. If asking in Slack takes 30 seconds and reading a doc takes 2 minutes, you already lost. Make the doc faster to find than the person. Pin it in the channel. Bot that answers with link.
Bruno22 said:
People here do not believe in documentation
Same same in Jakarta lah. My trick: when they ask me something second time, I say "I already write in README, you find yourself I busy now". Third time they remember, or they learn to search first. Hard at first but work eventually.
wrap it, ship it, pray it
RanggaDass
Member
This is the way. Pain is the best teacher. I do same with my VPS clients, after third "how to restart" I send them the wiki link and nothing else. Some leave, the rest learn.
Eleven years running an ISP taught me that customers will read exactly one thing: the bill. Put your important info there, or in the error message they see when service stops. Everything else is hoping.
walt22 said:
Customers will read exactly one thing: the bill
This is bleak and also completely true for email deliverability. I have seen people read bounce messages for the first time in five years because it meant money stopped.
SPF, DKIM, DMARC — holy trinity ✉️
mediaaustin said:
The real answer is nobody reads documentation. They read error messages.
Error messages are documentation. The distinction is arbitrary. What matters is information density at the point of need. A good stack trace with context outperforms a polished wiki every time.
20 years in this business and I will tell you what actually gets read: the runbook when pager goes off at 3am. Everything else is compost. Write your runbooks in the repo, keep them one page, test them twice a year or they lie to you.
IPv4, IRC, and irssi — fight me