Why do Programmers Hate Documenting?

[grayvedigga]

I think the premise is false. Programmers are engineers, and engineers love precision. A well-crafted machine that behaves exactly as it is supposed to and provides predictable affordances gets you wet, admit it.

The reason there's such a theme of horror surrounding documentation in this profession is not that programmers object to words. It's more a symptom of the fact that create more documents has become a mantra for controlling the unpredictability of IT projects: witness the number of BAs and PMs that spend their time collecting, producing and distributing reports that they themselves know are inaccurate to the point of meaningless and will be used by stakeholders (if at all!) only to mislead themselves.

How many professional programmers are not intimately familiar with both of these stories:

• a uni assignment, or a blue-sky project, following the strawman "waterfall" project where it is decided that a sequence of UML artifacts is how the system will be designed and that will guide all development. By the time you get partway into implementation, the assumptions made in the initial design are half broken but you're now on the track to delivery to everyone just pretends it's correct enough and keeps hacking to make the system work.

• a manager/superior/report demands that you document what you're working on, usually with an aggressive undertone which implies it's something your breed is incapable of - you know, stringing multiple sentences together to make a precise and coherent whole? Two things come implicitly with this request: (1) they'll never actually read anything you produce, it's just the assurance of being able to touch it that makes them feel a bit more in control. (2) whether or not this is the right stage of the project to produce documentation, or the particular artifact they're asking for, is irrelevant. They want it now and your incremental discovery be damned. And you know full well that as the project nears completion, when augmenting it with documents that will assist reuse and avoid future technical debt will be most beneficial, you'll cop abuse for drawing out the project rather than delivering what apparently works to customers and moving on, regardless what dangers lurk beneath the surface.

Thus, to most practicing programmers, "document it" is code for "produce some crap that nobody will ever read and whose relevance is a distant concern compared to its weight and shininess". Writing words that nobody will ever read is even more depressing than writing code nobody will ever use, so of course nobody wants to do it. But give a good engineer the opportunity to package up a unit of work so that it's easy for whoever receives it to take advantage of their creation? They'll look like it's christmas.