Skip to content

The Secrets of Computer Programmers: Why Programmers Hate Documentation


First, let’s be honest and up-front. Programmers don’t actually hate documentation. Programmers can type. They spend all day typing. Not only that, but they are not being tasked to write fiction but to write something they have an ingrained knowledge. Developers don’t hate documentation; what developers hate is wasting their time.

The developer ego and arrogance is something I will address in the future but we have all seen it. Those pesky developers think there time is more valuable than ours. I will show them! But there is more to it than that. It isn’t the arrogance an ego that drives the wedge between tech and the business on this concept is it utility. When the request for documentation comes it is not a request for useful documentation. What I often find strange is the complete disconnect between business lines and tech lines on the subject. Before we go forward let’s look at two scenarios, one at your local doctors office and the next in the conference room.

The Doctor’s office

I am not a doctor. I don’t understand medical lingo. When I go in for a check-up I nod patiently while the medical terms float in one ear and out of the other. Glancing at my medical chart I feel like a small child in a jumbo jet. I can physically read the symbols but I don’t understand. Because of this I have to trust what my doctor is doing and that his notes are sufficient. I have to trust that any other doctor could easily pick up my chart and run with it even if my physician used a non-standard approach. It is just the way it is. A layperson should not have to understand an expert’s documentation.

Now a trip to your local conference room

“Great work everybody, this project is a great success, a round of applause for everyone,” the PM congratulates the team. The business analysts clap, the stake holders nod in satisfaction and the PM beams with pride, this is his win, and the developers look slyly at each other knowing what is coming next.

“We just need one final thing from the dev team before we can call this project complete and move it behind us. The development team needs to document the code,” the PM states. The BA’s and the Stake Holders give an understanding look. They too would like to know how the project works. Ideally, they want to maintain it without needing a developer. Developers are expensive and a burden on the company. A lone programmer, too inexperienced to know better chimes in.

“It is already documented. Any programmer can take over where we left off. It is checked into source control and the automated build process is documented with the servers,” a senior developer sends a quick text to the junior developer to shut up. The PM responds.

“Yes, but you need to document so that we can all understand what you did. We don’t want to have to rely on a programmer to update this thing”

What just happened?

If you are in the enterprise world and have ever been involved with a software development project then you are familiar with the conversation I described above. The entire development team will now spend several weeks creating a document that is passable for the “team”. These documents can run several hundred pages. After a few review sessions the documentation is finally signed off and the project is complete. Unfortunately, the document is out of date before the ink is dry (or let’s be honest, the back-up is complete … who prints?)

Another disconnect also happens a few weeks down the line. Remember the implicit goal of the team? I will remind you, no programmers should be necessary to maintain the system, they are expensive and unnecessary. But then a trouble ticket is opened and the business decides to route them to the development team, after all, who better than a developer to answer a question about the system? It gets better from there, you see, developers do have their ego’s and attitudes so most tickets turn into a cyberwarfare of “did you read the document”, “yes I did, I promise” exchanges. This happens so much that experience developers often game the system to their advantage [take a moment to read this blog post from theDailyWTF (a tech blog)]. What is the advantage to this approach? This gives developers the ability to immediately know if a user has read the documentation.

That would never happen here! I can read your mind, reader. So let me ask you, have you read your developer documentation lately? I don’t mean skimmed it, I mean actually taken the time to read the entire document or set of documents. If you perform this exercise you may be surprised at what you find. In many cases it is just some snarky comments littered throughout and in others it is downright onerous. The intent, believe it or not, was never malice. The intent was to divine whether the document or documents were every read … by anyone … ever.

My favorite example came from personal experience when I was in college. I was working technical support for a company that will remain anonymous. The founder had sold the company five years before I arrived and as part of the sale he was required to author a technical, how-to guide that described the entire company, its history, its process, and how to use the software. This exceptional, bound document was required reading for all employees, contractors, staff, and was also distributed to customers. When I arrived I was handed my copy and told to read it and then sign an oath of affirmation [yes, I had to sign an oath that I read it]. When I was finished I went to the Director of H.R. and asked her if she had read the book:

“Of course, it is required reading. Everyone has read it. We even give it to the customers”

“Do you think it is appropriate to send out when the name of the sample user in all the stories is: Jack MeHoff?” (Note to non-native English readers. Jack MeHoff when pronounced aloud is a sexual act)

Her face turned white. In my innocence I had discovered what the founder had known the entire time. Nobody reads technical documents. (Ok, only technical people read technical documents)

I know what is on your mind now. “We have to have some sort of documentation.” I agree completely. Read on.

Is there a better way?

Actually, yes, developers have hated creating manual documentation for so long that an entire movement has been created in the software development community called: “Source as documentation”.

Source as documentation is a process and a set of tools that allow software developers to use the source code (the fundamental building block of software) as a “storage and update mechanism” for the documentation. Tools were then created to automatically create “readable” documents from the source. Have you ever read the MSDN (Microsoft Developer Network Documentation) all of the technical API documentation is automatically generated from source and user added content.

What are the benefits?

  • Documentation is directly tied with the code so it is never out of date
  • The documentation is focused on the primary readership, other developers, not business users
  • Source as document forces better organizational skills in projects
  • Integration with Source Control allows native version history and chance management
  • External documentation and requirements can still be embedded within the source

Want to read a secret? Developers love source as documentation. Not only does it free them from authoring an unnecessary document that provides no value but it reduces the technical debt of the project making it easier for multiple developers to work together on the same project.

We don’t ask our doctor to rewrite her documentation so that we can understand it so why do we ask our developers to? If you want to move your team past Zone 0 then you need to start treating them like paid professionals.

Ennis Lynch

Ennis Lynch

Ennis Lynch is a Professional Coach Based in South Florida. His primary area of coaching focuses on coaching Software Engineering Leadership. On occasion he does Agile Transformation work as well but prefers coaching at the Team and Individual level vs. the organizational level.

If you have ever wondered: is professional coaching right for you ? Are you a Software Engineering Manager, Director of Engineering, Director of Software Engineering, VP of Engineering, or CTO reach out for a free initial coaching session. Initial coaching sessions are the real deal, no hard-sells, no "here is what you would get if you paid". Individuals that receive a free coaching session will get a normal private professional coaching session of 90 minutes (30 minute onboarding + 60 minute coaching) and it will be up to you to follow-up if you want to continue with help on your journey.

Ennis Lynch

Be First to Comment

Leave a Reply

Your email address will not be published. Required fields are marked *