Documentation is a bit like people dying.

The illusion of control keeps our minds occupied.

http://www.independent.co.uk/arts-entertainment/music/news/michael-jackson-officials-threaten-to-close-munich-shrine-to-singer-after-fights-between-rival-fan-10433411.html

Let’s start by looking at what happens when someone dies. We keep a lot of their important possessions in order to hold on to that person. We are seduced by the artifacts of a life once real. We often get lost in the illusory world of ritual. We do this to ‘keep’ a part of them with us, or the feelings of completeness we once had. But alas, they are dead. No longer here. Harsh reality. We cling to artifacts and ritual—which are effectively illusions of control.

This is not said to trivialize tragedy or the vast importance of ritual, but we see a lot of manufactured ‘realities’ that continue on for decades, without much practical consideration or humility.

I feel a bit the same about process artifacts in software development processes. I consider process artifacts to be the general menagerie of written, sketched and designed media produced to eventually create working software—or the internal documentation of our ideas that lead to something real.

Process artifacts are great. They are necessary. Thinking through big ideas on paper is much less expensive than thinking in code or raw . We need schema designs, information architecture workflows, wireframes, UI designs and more. Yet consistently lost on management and executives is that building software is not the same as building an office park. An office building has a specific number of floors, parking spaces, toilets, light fixtures, etc. Software, by contrast, is totally organic, malleable, it stretches and shrinks, spreads broad and thin, consolidates narrow and deep.

Software is called “software,” not “documentation.”

There are only two important artifacts from a software process 1) automation, and 2) working software. Everything else is just the idea of software; the discourse surrounding the potential manifestation of a concept into digital/device form; a narrative about the construction of hypothetical software that could possibly materialize in a certain way.

Our wholesale inability to recognize the organic nature of building software, combined with an inability to accept the temporal and insignificant nature of artifacts, generally results in an abundance of documentation—very simply because artifacts make us feel safe, predictable, and in-control.

Artifacts are a bit like celebrity shrines.

A strange thing about celebrity shrines: the celebrity doesn’t care or notice because they’re dead. Shrines and memorials really just make us feel safe and in-control, that somehow we have power over the organic and mysterious nature of life itself. The shrine exists only as a declaration about our perceived reality, not actual reality. Similarly, our software doesn’t care about our excess artifact creation, because there is just no conduit between excess artifacts and working software.

Great artifacts are precisely tactical, yet allow for the mysterious unknown that comes from building a software system. The Agile folks knew this, and underlying their simple manifesto lies a deep understanding of the nature of organic systems. Appropriate amounts of artifacts can only be generated by a humble group that understands the finite boundaries of their knowledge and foretelling abilities.

Absent this fundamental faith in an ability to achieve without a facade of concrete certainty, the two toxic phenomena that I see most are 1) executive dissonance, and 2) artifact queueing.

Executive Dissonance

This is the difference in expectations between executives and high-performance employees. Most likely, your executive team stopped doing actual work a long time ago. They now spend their time selling product, creating partnerships, evangelizing, and raising money—all important things. They can’t raise money without certainty, or at least the facade of certainty. This is where artifacts plays a crucial role. It makes perfect sense.

Executives need to remember that just because they convince investors that artifacts are real, predictable and important, artifacts do not always manifest into actual product. Many artifacts (particularly written) are of little use to any high-performance employee. It’s much better to say, “I really need fantasy artifacts in order to raise money or secure this partnership, but next week I want to sit down with all of you to learn how we can tactically build to get from A → B. Please tell me how I can help accelerate, inform and be a part of your organic process (instead of pointing to pretty colored paper while declaring delivery dates).”

Artifact Queueing

Next to executive dissonance, we have artifact queueing. If we are correct to assume the unpredictable nature of building software, and that artifacts make us feel warm and safe, then the natural effect over time will be artifact queueing—i.e. producing vastly more artifacts and assets than can be built.

This is a particularly toxic practice, primarily because it completely ignores two things 1) the realistic throughput of a system, and 2) that small periods of time change everything—i.e. next week we might have vastly different assumptions about product, market, people and finance—assets produced this week may have no purpose and be completely misinformed next week.

If we can’t build it, then we want to talk about it. Our dev team is cranking for the next two weeks on important stuff, but our business team and UI designers have free cycles, so let’s get them producing high-fidelity assets together. And let’s make sure we have lots of meetings with management and executives to discuss hypothetical things that are anchored by a faulty view of predictable reality.

The scenario above might be a bit dramatic, but it’s incredibly common. This is why Agile, Scrum, Kanban, XP, Lean, and various ‘first-in-first-out’ or batch-constraining systems became popular. Quite simply, declaring software systems as predictable is actually insane, and forcing this fallacy on teams filled with technical, high-performance and creative people is horribly wasteful and corrosive to morale and productivity.

Just keep it moving.

Keep producing your artifacts, but keep in mind they just represent ideas, not real software. The more artifacts you create, the more artifacts you get. Your high-performance employees know this, and are probably tired of wasting their time.