On Documentation

Here’s a partial list of surprising things about human technology:

• Throughout history, when someone has learned something that they really wanted to pass on to future generations, more often than not they would write it down on paper – a material that is highly susceptible to damage due to water, fire, and the abrupt grabbing motions that seem to be hard-wired into toddlers everywhere.
• As tenuous as that sounds, it’s perhaps even more terrifying to imagine how much of human knowledge exists only within the heads of living people – and what would happen if a generation of working-age adults were suddenly wiped out. Even if good documentation existed, could a younger generation keep everything running smoothly without the [rolls eyes] accumulated wisdom of their elders?

I write explanations for a living; at the end of a good week, basically the only thing I can point at to justify myself professionally is a couple thousand words of descriptive prose. Heck, the name of this newsletter – a name which l feel a strong personal attachment to – is a reference to a document which spells out the work that someone has done or is going to do. And yet if you gave my unlocked laptop to a person of reasonably high competence, and asked them to continue my work while I sipped fruit juice on a desert island, it would surely take them weeks to understand how and why the various parts of my work life fit together. Most of my job – the rhythms I work by, the editorial standards I believe in, the psychological tricks I use to inspire myself on a daily basis – is so poorly documented that it might as well not exist at all.

I have not always been this way. Put me in a work environment that has the appearance of high standards but no documentation to refer to, and I’ll spring into action, issuing memos and scrawling “DO NOT ERASE” on communal whiteboards in an attempt to establish and codify something about the work done there. I am a finely tuned sensor for the hypocrisy of others, and the indignation I feel towards someone else’s undocumented project is a powerful motivator.

In the absence of indignation, what else might I (should I?) use as motivation to document my work? 

One answer is that I should do it for other people – the people I’m working with now, the people I might work with in the future, the people who’ll have to pick up from me once I’m gone. Documentation aids collaboration, the theory goes, and to the extent that the mark I make on the world is positive, any documentation I leave behind will make it easier to be maintained and built upon. Perhaps I should document my work so that others can understand it – the problems it attempts to solve, the strategy behind my approach, the logic I followed to reach a solution. 

In Managing the Flow of Technology, a book devoted to understanding corporate research and development lifecycles, Thomas J. Allen describes how information can become locked up inside physical artifacts. “Technology consumes information, transforms it, and produces a product in a form that can still be regarded as information bearing…[but] the physically encoded format of the output makes it very difficult to retrieve the information necessary for further developments.” I read this passage and I look up at my surroundings, at the house on which I’ve spent so much time working over the past seven years. A few months ago, I cut a hole through a wall to let speaker wires pass through. When the project was done, I felt a distinct feeling of progress. But looking back, does it constitute physically encoded information? Would it be difficult for someone else to retrieve that information in the future? If so, do I care? 

The reality is that I mostly don’t; the needs of this hypothetical successor are too abstract. And so I justify my documentation on more selfish terms. 

I document my work for the sensation of writing about it in the past tense. It gives a sense of completion, or at the very least of a transition, like the moment at which you give the final nudge to a child riding a bicycle for the first time. I document my work to give it significance, to retroactively denote a series of thoughts and motions as a project which I did. I document my work to convince myself that I should be proud of it, and to establish a framework in which I can understand it in the future, and to have something to point to when the work itself has been buried in time.