Why Programmers Hate Documentation

DEV.BIZ.OPS
Aug 8, 2017 · 3 min read

One of the first programming books I picked up was the “Camel” book. Anyone doing web programming in the nineties knows that was the O’Reilly book Programming Perl. Now those books collect dust on the top of my bookshelf.

I was using Perl to spit out webpages for a client/server database app I had written. There was no one familiar in my company to rely on, so that book saved my butt. I finally launched the app, it was a big hit and I left for San Francisco. Where were the docs for the awesome app I created? ¯\_(ツ)_/

We love good documentation, but it suffers from one fatal flaw; developers hate to write it. Gerald Weinberg, the father of the psychology of programming said it best:

The challenge becomes when to fit in time to document code. Engineers are evaluated on shipping code, not on the number of pages of docs. Not many businesses employ tech writers to create robust documentation for internal systems. And frankly, when to even begin documenting code can be a big question mark.

There are times when good, clear, concise documentation is necessary. But in an environment where tech & processes are moving so rapidly and with multiple, far-flung teams working on the code, documentation takes a backseat even when it is one of the most critical things a team must do.

I often share with dev teams the idea of in-flight documentation. The premise is simple; lots of people are working on the code, questions come up, and there should be a place to ask and answer those questions quickly. You capture that knowledge as you code. It takes no more than a couple of minutes to type in the question, and a few minutes for someone else to respond.

It is not a substitute for writing full documentation. But a knowledge database that makes it easy to ask, answer, share, search, and record can ensure not all the know-how is lost, especially on big multi-org projects, Dojo cycles, Agile sprints, Digital Transformation initiatives and the like.

So what is your documentation story like? Please do share and let’s find some time to chat soon!

Why is gold golden?

This is why Goldfinger still my favorite Bond film…


I help senior IT leaders and companies solve the challenges involved in digital transformation and moving towards a developer-centric culture that delivers innovation and customer value. In my day job, you can find me here.

DEV.BIZ.OPS

Written by

Thoughts digital transformation, enterprise IT agility, and how developers are writing the script for the future. Author is 👉 https://twitter.com/marksbirch

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade