The Art of Documentation
Seasoned programmers tease silver hairs from their scalp one by one, attaching each to a story about a time that docs failed to lead them—or worse, misled them.
“Senior” teams with shitty docs hire apprentices, then pat themselves on the back for “training them” by relegating them to documentation janitors (I said it).
Why do we suck at this, what does good even look like, and how do we get from here—wherever here is—to there—wherever there is?
Before we go through all that, I gotta address one thing first, and it’s going to piss a lot of people off. Get a cup of tea before you read this if you’ve ever found yourself, I dunno, ready to kneecap a stranger from Twitter over logarithmic complexity or something.
Technologists often feel guilt about having too little documentation, and that’s probably warranted—especially when the original implementers couldn’t be arsed to explain how anyone else might get it running or use it.
