Why Programmers Hate Documentation
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 success, and I left for San Francisco to pursue my Dot Com 1.0 Internet millionaire dreams. Where were the docs for the awesome app I created though? ¯\_(ツ)_/
We love good documentation, but it suffers from one fatal flaw; developers hate to write it. The father of the psychology of programming, Gerald Weinberg, said it best:
The challenge becomes when to fit time in towards documenting code. Engineers are evaluated on shipping code, not on the number of pages of documentation they write. 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 technology and processes are changing rapidly with multiple, far-flung teams working on the code, documentation takes a backseat even when it is one of the critical things a team must do.
I often share with developers the idea of creating 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. These answers then become the atomic unit of knowledge, easy to tag, index, and search.
This is not a substitute for writing full documentation, especially end user documentation. However an interactive, knowledge database that makes it easy to ask, answer, share, search, and record can ensure not all the useful know-how is lost. This becomes especially important on multi-team projects, Dojo cycles, Agile sprints, Digital Transformation initiatives and the like.
What is your process for creating internal documentation like? How do you determine what is necessary to document?
Why is gold golden?
This is why Goldfinger still my favorite Bond film…
We help IT leaders in enterprises solve the cultural challenges involved in digital transformation and move towards a community based culture that delivers innovation and customer value faster. Learn more about our work here.
