Your feedback is appreciated ...

Tech Management

Thoughts on Why Tech Folks Hate Documentation

Execution

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.

Discussion

4 comments for “Thoughts on Why Tech Folks Hate Documentation”

  1. [...] But how to encourage effective “findability” – especially when techs don’t like to document stuff? Back to Google for some guidance [...]

    Posted by cazh1 | Capturing Knowledge, and Making in ‘Findable’ (2 of 4) | June 6, 2010, 3:12 pm
  2. [...] may take place, but acceptance testing is cursory, technical documentation a pipe dream (to the delight of the techs), and volume testing happens with that first round of lucky users (oh, beta, right [...]

    Posted by cazh1 | The Iron Triangle – Quality is a Feature that We Choose to Omit from Projects | June 20, 2010, 7:03 pm
  3. [...] of course, as noted before, most folks don’t like to create content. If this is you – let go of your angst, [...]

    Posted by Search as the Killer KM App, and Good Writers will Rule the World | cazh1 | August 21, 2010, 9:16 am
  4. [...] 30, 2006 ⋅  Print This Post ⋅ Post a comment McDonald sent a nice comment on my last post – he’s writing a lot about project management lately, and we even chatted about some [...]

    Posted by Documentation Redux – a Shorthand Proposal Framework, and the PMO Surprise | cazh1 | November 8, 2010, 9:49 pm

Post a comment

*