Developers who don’t document code? Blame the bosses

One of the top enterprise IT complaints is that a serious lack of documentation — especially for legacy systems’ homegrown code — makes operations much more complex and riskier than they need be. 

What’s rarely discussed are the reasons why there’s such a severe documentation shortage. The sad truth is that the blame mostly lies with IT managers — particularly those in charge back when the coding happened and the documentation didn’t. (Before you judge your predecessors’ predecessors too harshly, how often do you insist that current coding efforts under your authority have comprehensive and accurate documentation?)

The documentation problem starts with a simple fact: Developers hate documenting their work — and they hate it for multiple reasons. 

First, it is the antithesis of fun. Coders often enjoy the creative elements of coding, but once they’re done, they want to move on to the next project. Focusing on the last one for a long time to document every aspect and explain every rationale is an annoying chore. Given a choice to avoid doing it, they will do so with alacrity.

Secondly, there’s the self-preservation aspect. Developers know if there is no actionable documentation, managers will be hesitant to fire or lay off that person because they might need them later. And speaking of needing them later, if a coder has left the company, they’re well lined up for a profitable consulting gig to solve the problem. Doing the detailed documentation work makes that little gig less likely.

In case you haven’t yet noticed, this age-old documentation issue shares a key trait with generative AI (genAI) testing issues — an impressive level of lack of self-awareness among senior managers about how they present these issues to their people.

I recently wrote for