The Documenter’s Manifesto

Disclaimer - thoughts are my own, and are not representative of any company or entity I work with or for.

Preface

The amount of people who forego documentation in the favor of "sexy" useless bullsh*t engineering solutions which often are not even practical is insane and a blight of the corporate world, which rewards siloing and fancy bullsh*t to line managers rather than actual engineering initiative to create and maintain working solutions which benefit the wider group.

I get it, humans are territorial. Maybe you see documentation as an invitation for people to stomp all over your lawn. But news flash, you don’t own the f*cking lawn. It’s 2025, and the best engineers share knowledge, not hoard it like some Gollum-ass gremlin whispering “my precious” over a YAML file.

The Intern Test

If you built something but didn’t document it, congratulations, you incompetent lizard. You have officially created a booby-trapped labyrinth that only you can navigate. If I have to personally summon you from whatever basement you dwell in just to figure out how to run your cryptic piece of garbage, then your project is a failure. If a sleep-deprived intern can’t use it without calling you, you f*cked up.

Stop Wasting Everyone's Time

You automate tasks because clicking buttons manually is for cavemen. So why the hell are you manually answering the same dumbass question fifty times every single week like some kind of corporate Groundhog Day? Write it once, shut people up forever. This is called not being an idiot.

Stop Trying to Sound Smart

Nobody gives a sh*t about your deep, philosophical insights into “hyperscaled cloud-native containerized microservice orchestration methodologies.” Nobody. Just tell us what to do. If reading your doc takes longer than actually doing the thing, you should Ctrl+Alt+Delete yourself from tech and start an artisanal jam business instead.

Longer Than 5 Minutes? You Already Screwed Up

Nobody opens a document hoping for a f*cking novel. If your doc is longer than a five-minute coffee break, it belongs in a bonfire. Get to the point before I die of old age.

Action First, Nerd Rambling Later

1. Tell me what to do.
2. Tell me why, but only if I care.
3. Oh wait, I just read 2000+ words and realized I don’t care. Sh*t.

Imagine if I spent that time actually getting things done.

If your documentation doesn’t immediately tell someone what action to take, then you can stick it where the sun don't shine.

Standardize or Get Off My Internet

If every one of your docs is utterly different, then you are utterly uncommunicative. Use templates. Make things predictable. If I have to play Indiana Jones and the Temple of Your Garbage Docs just to find basic information, then I am rolling that boulder down straight on your cube.

Old Docs Rot Like Expired Yogurt - Delete That Sh*t

If nobody has touched a document in months, it’s probably as useful as a Windows Vista manual. Either update it, delete it, or shove it into a dark corner where it won’t waste anyone’s time. Outdated docs are worse than no docs at all.

The Ultimate Bullsh*t Killer

Every second you spend writing a proper doc saves hours of annoying messages, confused engineers, and meetings that should have been emails. If you actually like being interrupted, I have bad news about your brain.

If You’re Drowning in Work, It’s Your Own Damn Fault

If you spend your entire day answering the same stupid questions, you are literally doing this to yourself. Good docs scale knowledge deployment. Lazy engineers don’t document. Smart engineers do. Which one are you?

If You’ve Had to Explain It Twice, Document It or GTFO

The first time someone asks, fine. The second time, it goes in a doc. The third time? If you’re still explaining, you deserve whatever suffering comes next. Learn. Adapt. Write it down. Be less useless.

Final Thoughts

Bad engineers only write code. Great engineers write code, but also make sure they never have to deal with idiots again. Write the docs. Save yourself. Save us all.