You Can Click the Link, It Won’t Help You
There’s a special kind of reassurance that comes from being told “the details are documented”, at least for the management class.
It sounds professional. It sounds organized. It sounds like someone has done their job.
“Tick, tick and tick”
Yet under the surface there is an alternative fact. You open a ticket, and what you actually find is
A half-written sentence
A link to another link
Welcome to a guided tour of someone else’s avoidance strategies, differing from your own since you have no way out of this one.
Distributed Context
Everything is there. That’s a refrain I’m used to hearing, and it’s seldom true. Because teams are happy with information as long as it is somewhere but the problem is nobody really cares where that somewhere might be.
That’s not clarity, people. That’s the opposite.
The requirement is in one place.
The rationale is in someone’s head.
The edge cases are in a Slack thread from three weeks ago.
The acceptance criteria are “obvious”.
This isn’t documentation. It’s a distributed systems problem, except the nodes are people and none of them are reliable.
You might be in a worse predicament, one where the person with the pertinent information has changed teams or simply “doesn’t remember” where the information is.
Suddenly you’re no longer creating a feature, you’re a member of an archeology department and nobody knows where the head of the body might be.
Tools Don’t Create Clarity, People Do
The thing is that the problem isn’t the tooling. You can replace the tracker, rewrite the process, add more fields, enforce templates, or introduce a new ceremony named after a sport.
You can’t replace the people.
You know the ones. The ones that get stuff done, but never write things down. Those people who don’t explain why decisions are made or respect the time of anyone else in the team.
But we don’t tend to say that people are like that. We don’t advertise their jobs looking for anyone social or easy to work with, so why are we surprised with the outcome of people who just aren’t that?
“Just Ask If You’re Unsure” as a Process Smell
There’s always someone who says “Just ask if you’re unsure”.
That puts the responsibility for the communication on the receiver rather than the sender, which is not how things should be done if you know anything about computer science.
Perhaps you think that a receiver should poll the sender to see if a message has been sent? I’m here to tell you that’s not the way that things should be done
What they really mean is:
“We didn’t bother writing this down, and now the cost has been externalized to you”
Interrupt-driven knowledge transfer doesn’t scale.
It privileges the loud, the confident, and the constantly available.
Everyone else just learns to stop asking and start guessing.
That’s how bugs happen. That’s also how resentment builds
Writing It Down IS the Work
Clarity is not a nice-to-have.
Context is not optional.
And “we’ll explain it later” is just future technical debt with better posture.
If something matters, it should be understandable without a guided tour, a meeting, or a detective novel.
If it isn’t, then at least be honest and say so.
When you’re pushing code you’re really pushing business logic into production. You’re extending how problems should be resolved in the same way as any process person would do so. We’re simply not cognisant of the fact that we, as programmers, own the explanation as well as the execution. Period.
Conclusion
Yeah, you should be documenting things. Sorry about that.
About The Author
Professional Software Developer “The Secret Developer” can be found on Twitter @TheSDeveloper.
The only documentation The Secret Developer produces is the blog you are reading right now.