Thoughts on Why Tech Folks Hate Documentation

I’ve had some flashes of insight on why technical folks don’t like to document stuff. Currently, I’m thrashing thru a skunkworks project that is evolving into something that will need to be reasonably available, robust, etc. I’m also trying to lead by example; I ask my teams to build for sustainability and document so they can “walk away”.

Of course, I’m also lazy – I really don’t want to explain things over and over again.

However, the time crunch I face is the planned departure of the person who does this “stuff” manually – my automated solution is the only replacement strategy, and the deadline fast approaches. Still, I am forcing myself to document to a reasonable level of quality, and so I’ve come to these “insights” in a caffeine-induced late-night buzz.

Anyway … the Reasons Techs Don’t Document get progressively deeper

  • Double Work = Waste of Time: I wrote it once, in the code – why should I rewrite? Capturing business rules in the code is just another way of writing it all out – aren’t we just quibbling over the language? (or the language?) And besides, isn’t self-documenting code a circular statement, a oxymoron for the competent programmer?
  • Readers are Impatient, Coders are Complete: Tech folks like to be thorough, with plenty of details. It’s a form of showing off, letting us all know they understand the depth of the solution. Except – most readers don’t want all the details, they need the correct level of detail so they can get their job done. Too much, and it all appears more complicated than it really is; the reader’s brain shuts down, and they don’t get the message. The Author will think the Reader doesn’t understand and/or appreciate the solution to the depth required, so they add more, and the vicious circle winds down until the Author drops it and/or the Reader ignores it. Heu infandum, yada.
  • Prose = Coding Straight to Production: A programmer’s work product is hidden (coded) in the source, but writing is more direct. Getting a compiler to complete with no errors and warnings is an automated way to make sure your basic message is clear. Yes, you could have a logic error, but it’s still enough to make the computer do a lot of non-trivial stuff. People, on the other hand, when reading to grasp a reasonably difficult concept, will shut down after relatively few grammatical errors (if the author can’t spell or punctuate, how good can the substance be?) Plus, compilers don’t make you feel stupid when you keep making the same mistake over and over (relatively few judgmental error messages).
  • Prose Is Too Abstract: Back in the old days, we learned programming with Assembler, COBOL, Basic, Fortran – single-threaded, top-to-bottom, procedural, “offensive” (the program controls the user). Next came GUIs, OO, “visual” programming; event-driven code, moving to a “defensive” posture (the user controls the program). Still, the application defined a finite set of events that could happen, so there were always limits. Unfortunately, writing is infinitely unpredictable; there’s no telling the mindset of the reader. You have to anticipate a lot, yet you are typically forced (by the medium) to adopt a single thread – the Table of Contents – as the primary organizational structure.

Personally, I don’t think lazy coder is the ultimate reason. More like unpredicatable reader – it takes a lot of empathy and imagination to think about how others perceive your work.

Which is probably why most techs can’t do effective user interface work, either.

This Post Has 0 Comments

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Related Articles

Accelerate Innovation with a Simpler Budget Approach

Organizations are desperate for innovation, but these are still investment choices that require complete and credible data to enable the right decisions. Developing a simple standard for characterizing all costs will accelerate decision making.
read more

More Thoughts on Why Techs Don’t Like Documentation

A few years ago, I was interviewing candidates for a systems analyst job, and trotted out one of my standard…

read more

James MacLennan

... is the Managing Partner at Maker Turtle LLC, a digital consultancy focused on creating value in ways that align with your strategy and drive engagement with employees, customers, and stakeholders. He is an active creator, providing thought leadership through on-line & print publications, and public speaking / keynotes.