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 our sister publication CIO.com about CEOs who tell investors and the media that they fully intend to deploy genAI tools to reduce their workforce — especially coders. They then turn, with almost precise comedic timing, to their coders and ask them to test the genAI systems. 

Those CEOs might have just as easily said, “As soon as we can prove that these genAI systems work, we will lay off thousands of our technical team members. (Turns to those technical team members) Please test these systems. It will be your job to determine if they work reliably enough for me to lay off all of you. We will trust your reports.”

IT managers are in many ways doing the same thing when they ask programmers to create detailed and complete documentation for all of their code. Fortunately for the developers, those managers rarely make that request — and they certainly don’t insist on it — for a few reasons.

As much as coders want to move on to the next project, their managers often want that even more. Because once an app or coding tweaks are done and approved by the line-of-business manager who wanted it, IT types want to move to the next 19,000 items on their to-do list. 

They don’t want a programmer to spend a day or more documenting details about the now-completed project. And therein lies the mental disconnect. That IT manager will allow and encourage that coder to move on and skip meaningful documentation. And yet that manager will scream about the lack of documentation for legacy code written 18 years ago.

Connect the dots, people: that lack of documentation is because the person who held their position 18 years ago did the exact same thing they just did.

How can this problem be fixed? There are a few options.

First, you have to realize there are actually three distinct problems that overlap: Problem One involves code created a long time ago where the original coder is no longer available; Problem two, involves code created more recently, with the original coder absolutely available; and Problem three involves code your people are writing right now.

As an aside, we should ask whether genAI coding assistants could help. If the problem with coders was solely related to, “It’s boring. I don’t want to do it,” then AI tools could make a big difference.

But we do have that programmer self-preservation factor. It’s not just that they don’t want to create the documentation — they don’t want the documentation created by anyone. 

To be sure, IT managers would be fine with AI creating the documentation if possible, because it negates their big concern; they want the coder to move onto the next project.

But applying genAI after-the-fact, where the algorithm tries to guess a coder’s intent with each line, is likely to cause more problems than it resolves. The only way would be for the AI agent to work with the coder every step of the way to understand the full coding process. 

In a vacuum, this could solve the issue. But remember — a coder’s financial objective is to stick around and not document themself out of job. Cooperation might be less than enthusiastic.

This brings us to genAI. Could today’s AI agents do a better job of figuring out what is causing a problem in legacy code and figure out how to fix it? And if that were possible, would that reduce the need for documentation?

Adam Resnick, a research manager at IDC, said the documentation issue is a constant concern for enterprise IT. “Poor documentation can make legacy systems harder to modernize, and makes onboarding, security audits, bug resolution, and maintenance more challenging,” he said. 

Resnick sees the problem as being an issue of IT priorities: “Enterprises place a high priority on delivery of new features or urgent bugs under tight deadlines, and developers are incentivized towards these goals. Devs get raises and get promoted based on output, not documentation.”

But coder resistance has a lot of psychology behind it. 

“Documentation is considered by many devs to be tedious and unnecessary. It takes a lot of time to document well, and devs who feel that they are writing good code often feel that anyone should be able to look over their code, and understand it without a lot of trouble,” Resnick said. “I’m not saying that developers are justified about the ‘unnecessary’ argument, but if they consider documentation tedious, then to them it is tedious. Very few ambitious developers place documentation high on their list of what they’d like to spend more time doing.”

But the problem gets worse the older the code is. 

“Documentation is almost always behind, as systems evolve quickly. It is time consuming to update legacy documentation, which is often outdated by many cycles. Enterprises are unlikely to devote the amount of resources needed to catch up,” Resnick said. “Developers are under pressure to deliver new features and fix bugs, [and] are not incentivized or motivated to spend a high percentage of their time on documentation.”

Like almost everything else in IT, throwing money at the problem can actually work. “Incentivize developers to document,” Resnick said. “Tie fat bonuses to documentation and you’ll get more documentation.”