Write it down: the discipline of documentation
I’ve been reading Mythical Man-Month, and it has so many sharp insights (yes even for a non engineer like myself). I’m narrowing in on one today on the discipline of documentation. We’ll start with a lovely quote from the essay “Why Have Formal Documents?”
“First, writing the decisions down is essential. Only when one writes do the gaps appear and the inconsistencies protrude. The act of writing requires hundreds of mini decisions, and it is the existence of these that distinguish clear, exact policies from fuzzy ones” (pg 111, Mythical Man-Month)
If if I could insert some sort of reactji/loud cheering GIF here this would be the spot. Today I’ll cover:
1/ Reasons why we don’t document
2/ The impact of not documenting
3/ Over-documentation
1/ Reasons why we don’t document
- Time pressure: There are many things going on, bandwidth is constrained. Having to document is another burden/time sink.
- Unwillingness: Feeling its unnecessary, a nuisance, a distraction, and not wanting to do it out of laziness.
- Vulnerability: Writing things down means having to defend it. It might be hard to do so when some ideas need pressure testing, and aren’t fully fleshed out yet. Some workplaces don’t create a safe space for critique, and so that might cause one to hold back from documentation. To quote another Mythical Man-month essay (“Plan the Organization for Change”)
By documenting a design, the designer exposes himself to the criticism of everyone, and he must be able to defend everything he writes. If the organizational structure is threatening in any way, nothing is going to be documented until it is completely defensible”. (pg 118, Mythical Man- Month)
2/ The impact of not documenting
If the benefit of a written plan is precise communication with a crisp sense of direction, then the lack of documentation causes the opposite effect. Besides unclear and imprecise communication, the other effects are:
- Increased communication load: One has to repeat/teach the same topic more, there are more meetings to clarify items, or meetings are less productive and wastes peoples time. There might be more confusion and misunderstandings. It’s harder to ramp newer team members as common knowledge might be unknown to them. Everyone’s drained as a result.
- Squeakiest wheel gets the oil: The loudest voices haphazardly opining on slack in multiple channels gets the attention. This is versus a more more impartial evaluation of different ideas written down, and clarified.
- Poorer thinking and decision making: Iron sharpens iron. A good idea written down can be refined, debated and shaped into an even greater version. I believe this is the bigger and more unfortunate waste.
3/ Over-documentation
I’m adding a caveat here that it’s not that boundless, lengthy documentation will cure of all miscommunication, unclear thoughts, and poor decision making. Documentation helps, but it can also be overdone if:
- Documents created are all of different structures and lengths. Amazon did say a 6 pager for a reason (though I have heard that the Appendices get very long). There’s value in templates, common structures that help standardize how information is presented and communicated.
- Documentation becoming more highly prized than execution. It could be that repeatedly writing good docs are what gets the promotion/ visibility vs actual creating software/products. I don’t have the answer to how companies prevent this from happening.
- Documentation becomes a tool to punt difficult conversations. Instead of discussing a hard problem, people are are punted with a “please write a doc”. Sometimes writing a doc on a hard problem is helpful. But it can also be an excuse to kick the can down the road.
Who wants less meetings or reading through slacks to try guess the latest on something? Who wants to be a sender and receiver of focused thought and crystallized decisions? Who wants everyone to be journeying in the same direction?
The discipline of documentation might not be the ONLY way those goals are achieved, but it’s hard to see how clarity, focus can be obtained without good documentation.
