The Benefits of Documentation

Problem

For many people, writing and documenting things is a burdensome activity that requires a significant amount of effort. However, its benefits by far outweigh any discomfort of putting some extra hours in writing things down. Not only does documentation help organize and streamline our collective knowledge, but it also has a beneficial impact on us as individuals. Moreover, the Covid-19 pandemic profoundly changed the way we work and communicate with each other. Now, when online collaboration is more important than ever, documentation becomes a fundamental method of communication.

Actions taken

Key benefits

If I don’t write something down, I will struggle to articulate myself concisely and accurately express my thoughts. For example, if I have an important one-on-one with someone, I would jot down a script. I will write down all of my thoughts, and only then would I be able to identify difficult parts that should be further explained. I would discard the script after it would be completed, but the sheer effort of writing it down would improve the quality of the meeting immensely. I find some explanations just hard to come up with right on the fly and prefer to have an opportunity to think and articulate my thoughts through writing.

Also, documentation is essentially communication automation. If I don’t write something down, I will have to explain the same concept to different people multiple times. If it is written down someplace, I can always refer people to that exact document and let them read it when it suits them the most. I would provide them with a high-level summary, but I would spare them details that are outlined in the document. Considering that I am weekly compiling between 10 to 20 documents sent out to 150 or 200 people, the benefits of documentation are rather evident.

Finally, documentation allows people to add their comments asynchronously and thus bounce their ideas off for an extended amount of time. The whole process would resemble a never-ending meeting where people could chime in, adding their suggestions months after. I couldn’t think of any other way for people to collaborate so effectively as through asynchronous documentation. This became particularly important during the Covid-19 pandemic; while the overall meeting experience was degraded, asynchronous collaboration remained very effective.

How to do documentation

As people are growing into capable technical leaders, they should become competent in writing code as well as developing technical strategies. Regardless of their scope, the main output of a technical strategy is a document that should provide stakeholders sufficient information and initiate discussion among them. Part of my coaching efforts would include asking my reports to draft a technical strategy, either as a solution proposal or problem analysis. Then I would have them ask stakeholders to sign off or comment. Everyone should be able to acquire this skill which is a part of the promotion package and directly contributes to people’s growth.

To make it easy to understand and browse our team’s documents, I created the Index Tree with around one hundred documents, all listed in one single Google Doc. It consists of onboarding documents, monthly newsletters, strategy documents, meeting summaries, and documentation of some typical management discussions.

Lessons learned

• Writing can be a strenuous activity. It takes some discipline to make yourself write something before you act. But it will pay off. If I feel that my thoughts are blurry and lack clarity, I will write them down, and they would become more lucid and precise.
• I would approach many complex problems by writing them down first. For example, sometimes there are complex or subtle issues to discuss with several or one person, I would jog my thoughts down in a lengthy Q&A format and share with the stakeholders. It will not only help me better understand the problem but also gain trust with the stakeholders who would be able to understand my thought process better. I find it very effective driving 1-on-1 conversations.
• During the Covid-19 pandemic, interpersonal bonds between people weakened because the sudden disappearance of physical connections started to erode trust between people. Furthermore, the overall distress caused people to disagree with each other on technical issues more likely. While building trust is crucial in the long-run, documenting things -- what people agree and disagree about -- can bring clarity and is far more effective than talking over the conflict.
• In the beginning, I tried to enforce a rather standardized way of writing things down, but eventually, I realized that people have their preferred method of writing. It is much easier to let everyone write in their own style. However, I had to learn how to provide feedback for a document that was entirely different from what I would draft.