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 is Coding Straight to Production: For the programmer, the work product is hidden in the source code, but writing is a direct read. 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 stucture.

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.