I’ve sat in enough sprint retrospectives to know how documentation comes up. The team ships the feature. Someone mentions the docs. There’s a moment of collective discomfort. “We’ll get to it next sprint.” Next sprint comes. There’s a new feature. The docs don’t get written. Six months later, a new developer joins and spends a week figuring out how the system works from the code alone because the documentation assumes context that was never written down.
It would be easy to call this laziness. It’s not. The reasons developers avoid documentation are structural, and understanding them is the only way to actually fix the problem.
The person who built the thing is, in many ways, the worst person to explain it to a beginner. This is called the curse of knowledge: once you understand something deeply, you lose access to the experience of not understanding it. The developer who built the authentication system knows which edge cases matter, what order to do things in, and which configuration options are actually necessary. But that developer has forgotten what it felt like to encounter this system for the first time. Their documentation skips the steps that feel obvious to them and are completely opaque to everyone else.
Documentation also has no tests. If a function breaks, the CI pipeline catches it. If a documentation page is wrong or missing, nothing fails. The system keeps running. No alert fires. The only feedback comes from users who got lost, and often that feedback arrives as a support ticket attributed to a product problem rather than a documentation problem.
And documentation rarely appears in performance reviews. Engineers get recognized for shipping features, closing incidents, improving performance. The technical writer who spent two weeks restructuring a confusing part of the docs and reduced support tickets by 30 percent has a harder time making that case in a quarterly review than the engineer who shipped a visible feature.
These are structural problems, which means they need structural solutions.
Making documentation part of the definition of done is one of the most effective changes a team can make. A feature isn’t done until the docs are written or updated. This sounds simple and it is, but it requires someone with the authority to hold the line, and a team that has internalized the idea that a shipped feature without documentation is an incomplete product.
Treating a pull request without documentation as an incomplete PR is the code-level version of the same principle. If a PR changes behavior or adds a user-facing feature, it should include a documentation update or a documentation ticket. Reviewers should flag the absence.
The Write the Docs community has resources specifically for building documentation culture on engineering teams. It’s not just a conference for technical writers: it’s a community for everyone who cares about documentation, including developers who want to write better and engineering managers who want to build teams that do.
I’ve seen this from both sides, as a technical writer embedded in engineering teams and as a developer advocate working alongside engineers who never thought documentation was their job. The ones who changed their minds did it because someone made documentation part of the process, not an afterthought to it.