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
- 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
- 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.