Tag Archives: simplicity

“Documentation” is a Dirty Word

I just skimmed through another 20 page planning document, written in old-school “requirements specification”-ese with a hefty dose of ambiguity. You know, things like “the Project Manager shall…” and “the technical team will respond to bugs.”

There’s a lot of good content in there. It’s not easy to get at, though… for each page I want to understand, I can expect to spend between ten minutes and an hour deciphering what’s going on. (That’s half a week of work, and I have a lot of other work to do this week. Is it even worth it?)

Also, this document is boring… and there’s a lot of filler (like “package X is useful, flexible, and open source” – OK, that’s great, and factually correct, but not very informative).

The whole document could have been condensed into 4 or 5 slides of diagrams plus annotations. If that had happened, I’d be looking at a 10 to 30 minute commitment overall to get my brain into this particular company’s context… and then I’d be able to make some useful contributions. (As it stands, I’m weighing whether it’s worth my time to go spelunking in that 20-pager at all. Probably not.)


  • The bulk of technical documentation that I read is unintelligible or lacks sufficient meaning. I have three decades of exposure to this stuff, so if I can’t understand it, I feel super sorry for the early career people (who might think they can’t understand it because they don’t know enough).
  • Nearly all of the technical documents I see are uninteresting. And tech is interesting.

99 times out of 100, technical documentation is dull and dysfunctional. While it’s supposed to help people and teams establish a shared understanding of a system or a process or a concept, it just ends up looking really impressive and convincing you that the authors know a lot more about this than you do. It doesn’t help you much, if at all.

And as a CTO, CIO, or VP of Engineering, I don’t want to pay for crappy documentation. This particular document probably cost me between $32K-50K, and that’s just the tip of the iceberg… because it doesn’t account for the incremental costs of the people who will attempt to decipher it – which could be 10-100x more over the lifetime of that document. Although the person or team that wrote the 20-pager probably knows what’s going on (at least a little bit), the artifact itself is going to cost other people time and take them away from more value-adding tasks.

The sheer volume of information we’re required to wade through to gain understanding – without the assurance that it will lead us in the right direction, or even in any direction at all – is probably what’s led to the disease of devaluing documentation

A lot of managers think documentation isn’t value-adding, and shouldn’t be done, because… in most cases, people do it so badly that it wasn’t worth the investment in the first place.

Dear tech workers: can we fix this, please? I know it will take a whole generation to effect meaningful change, but… I’m ready to roll up my sleeves.

Eight Ways to Deal with Complexity

There is not one person I know who doesn’t have to deal with complexity in their work or personal lives. Either the subject matter they work with is complex or specialized, the politics are stressful, or there’s just too much information to process and the information overload becomes oppressive.

Fortunately, dealing with complexity has been the subject of recent research and there are some lessons to report. These lessons revolve around the importance of “sensemaking” – a term coined by Karl Weick to reflect concerted effort made to understand the relationships between people, technologies, places and events, how they behave, and how to respond to their current and future behaviors.

Weick and Sutcliffe (2001) studied the environments of aircraft carriers, nuclear power plants, and fire fighting teams – situations where the stakes are high, and on-the-job errors can be costly and dangerous. These are the workplaces “that require acute mindfulness if they are to avoid situations in which small errors build upon one another to precipitate a catastrophic breakdown.” Snowden (2003), who worked at IBM, said that most environments just weren’t like that – so it would be difficult to generalize how those workers dealt with complexity to the typical office.

Browning & Boudes (2005) compared and contrasted these two studies to try and define some guiding principles for how people make sense of complex scenarios. Here’s a synopsis of what they found:

1: “Acknowledging and accepting complexity is better than placating it with planning models. There are simply too many situations where the standard tools and techniques of policy-making and decisionmaking do not apply.” The lesson: move away from a “training culture of obedience” and towards a “learning culture of understanding and action”. (This will be a challenge, because it requires humility and trust.)

2: “It is important to acknowledge failure and learn from instances of it.” Self-explanatory, but as above, this requires humility and ego-transcendence. For people to learn from failure, they must first confront it. I can think of some “death march” software projects where failure “never” occurred!

3: “Self-organization is an order that has no hierarchical designer or director.” Browning & Boudes cite Peter Drucker’s idea that “in the Knowledge Economy everyone is a volunteer.” Volunteerism means that everyone is fundamentally qualified to do some part of a project, that roles shift to accommodate existing talents and the development of new talents, and that if a person isn’t working out in one role, they can move to another. In volunteer contexts, leadership is often dynamic, where everyone serves for a time as the leader and then moves on.

4: “Narratives are valuable for showing role differentiation and polyvocality.” There are many voices, and many perspectives, and these can be effectively communicated when people relate to one another through stories and examples. Diversity of opinion and distance from a problem can help raise solutions – but the people who know the situation best, and who are closest to it, must be open to the possibilities. (Easier said than done.)

5: “Conformity carries risks, and thus we need diverse inputs when responding to complexity.” The authors suggest that learning should be valued over order and structure. This does not mean that order is unnecessary, but that any order that is established should be viewed as temporary – a framework to serve as the basis for new learning.

6: “Action is valuable under conditions of complexity.” Acting, learning, and adjusting is more effective and more productive than trying to identify the right solution, plan it, and then do it. Action builds identity and creates meaning; “the most useful information is contextual and need-driven.”

7: “The focus is properly on small forces and how they affect complex systems.” The authors suggest that focusing on small wins and keeping things simple is a strategy for success. I love the following story that they describe, so I have to include it here:

Snowden relates a story of two software development groups – one expert, the other a lesser group – whose experience in programming was limited to the fairly routine requirements of payroll systems. In a competitive exercise between these two groups for learning purposes, the experts created a plan for an elegant piece of code that would take two months to develop. The payroll programmers, meanwhile, downloaded a “good enough” list from the Internet that cost five dollars (Snowden, 1999). Thus one feature for smallness for Snowden is the decisions that can be made that allow the group to move on – to accept “good enough,” implement it, and then see what that action means.

8: “It is important to understand the irony of bureaucratic control.” Producing data and information can be overwhelming; innovative achievements can be suffocated by measurement, evaluation and control. We assume that organizations are deterministic and behavior can be programmed, using carrots and sticks. But people are neither rational nor linear, and this can be both the strength of the organization and its Achilles heel.

New organizational models are needed to be able to follow this advice. So many of the projects I see today are like solving mysteries: you know what needs to happen (because you have requirements documents), there are motivated people all around you who really want the mystery solved, someone is footing the bill (at least for a while), and everyone wants to make progress. But because the process is full of learning new information, finding clues, and relating to people’s needs – it’s impossible to put a timeline on it. This frustrates project managers (and their bosses) immensely, because their jobs revolve around bringing some order to complexity and setting expectations in terms of time and budget.

Can you imagine a crime show like Law & Order starting out with a murder – and then you cut to the scene where the police chief says: “We need to solve this murder immediately… all the clues need to be found by next Friday, all the suspects interviewed by the following Wednesday, and then I want a report on my desk with the solution three weeks from today!”

It sounds funny, but this is exactly what plenty of managers are trying to do right now in their own organizations. The “corporate consciousness” will support this kind of behavior until a rational alternative is found.

Browning, L. & Boudes, T. (2005). The use of narrative to understand and respond to complexity: a comparative analysis of the Cynefin and Weickian models. E:CO, 7(3-4), 32-39.
Snowden, D. J. (1999). “Story telling: An old skill in a new context,” Business Information Review, 16 (1): 30-37.
Weick, K. E. and Sutcliffe, K. M. (2001). Managing the Unexpected: Assuring High Performance in an Age of Complexity, San Francisco, CA: Jossey-Bass.