Why should you spend time documenting?
The short answer is:
Without documentation, systems fail and progress is lost. Our civilization collapses.
The collaboration coefficient
Humans are not only curious, they are great collaborators. Humans are the only species on earth that can collaborate in larger groups. The modern economy is in some ways a collaboration of billions of people. This collaboration is far from optimal in a mathematical sense, but it is happening. Some groups collaborate (e.g. Snowflake and Snowboard) and some don’t (e.g. McDonald’s and HelloFresh).
Let’s imagine we could measure cooperation around knowledge in a collaboration coefficient.
To explain the concept I want to introduce you to Ted from Ireland and Liu from China. They are on an exchange semester in Spain and must organize a welcome event for the other students. They don’t speak a shared language.
Their collaboration coefficient will be very low (close to zero) and the event will be as good as if one person organized it.
Let’s assume they can write things in a document and use a translator to plan the event. With these tools, they might be able to bump their collaboration coefficient up to 80%. The event they organized is so good, it could not have been done by a single person.
Indeed it was so good, that they get the task to organize this event at other universities. Unfortunately, Liu falls in love with a French girl and decides to take a bus to Paris (see the bus-factor https://en.wikipedia.org/wiki/Bus_factor) 🚌. Felix from Germany can jump in, reads the document, understands how the event was organized and what he needs to do. The collaboration coefficient between Ted and Felix remains high.
Without the document, Liu’s part would have been incomplete, although it held the secret why the event was so successful (it had something to do with cocktails 🍹).
The downward spiral
Of course, in the case of a student welcome event, this seems trivial. But if you extend that to software systems and data landscapes that are the result of 10s of thousands of hours of work, it becomes clear that we need tools that help with knowledge transfer. The failure to put these in place will result in a loss of knowledge about these systems. This loss can even start a downward spiral.
The engineers need to resort to more and more trial and error to get things to work, bugs come out of the blue, the engineers get stressed, one of them leaves, more parts of the systems are black boxes now, more bugs, more stress, more people leaving, ... 💥
“You do not rise to the level of your goals. You fall to the level of your systems.” - James Clear
In his book “Atomic Habits” James Clear mainly writes about people, but this is also true for other entities like software, companies, technologies, or civilizations.
“Without generational [knowledge] transfer, civilizations die” - Jonathan Blow https://youtu.be/ZSRHeXYDLko?t=932
Why now?
- In the context of a company, a generation is the working employees. In the past, it was not uncommon for people to learn at a company with 16 and then retire at the same company with 61. In the gig economy, there are a lot of people who have limited contracts. High-growth companies like Google have an average retention time of only two years.
- Because of the pandemic, more knowledge workers than ever collaborate remotely. Remote work is better with asynchronous communication because it reduces costly context switches. (See Remote Manifesto from Gitlab, https://about.gitlab.com/blog/2015/04/08/the-remote-manifesto/#2-communicate-asynchronously)
Companies that want to thrive in this environment need great tools for knowledge transfer. Documentation is a great tool for knowledge transfer. It transfers between people’s minds over space and time.
Who would know that better than Stephen King when he writes:
“What is writing? Writing is telepathy. [...] Look- here's a table covered with red cloth. Onit is a cage the size of a small fish aquarium. In the cage is a white rabbit with a pink nose and pink-rimmed eyes. [...] On its back, clearly marked in blue ink, is the numeral 8. [...] The most interesting thing here isn't even the carrot-munching rabbit in the cage, but the number on its back. Not a six, not a four, not nineteen-point-five. It's an eight. This is what we're looking at, and we all see it. I didn't tell you. You didn't ask me. I never opened my mouth and you never opened yours. We're not even in the same year together, let alone the same room... except we are together. We are close. We're having a meeting of the minds. [...] We've engaged in an act of telepathy. No mythy-mountain shit; real telepathy.” Stephen King - 2000 - Bangor, Maine
.jpg)
