The Benefits of Documentation
18 March, 2021

Justin Zhang
Sr. Director of Engineering at CertiK
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.
Discover Plato
Scale your coaching effort for your engineering and product teams
Develop yourself to become a stronger engineering / product leader
Related stories
5 December
Your Org Team may as well be a Sports team. Let's explore how this cohesive, multi-skilled team can be optimized for Great Group Playoff.

Jaroslav Pantsjoha
Google Cloud Practice lead at Contino
25 October
Mrunal Kapade, an Engineering leader, based in Silicon Valley, shares tips that helped reduce attrition in the remote engineering teams while leading multiple teams from startups to Fortune 500 companies.

Mrunal Kapade
Director of Engineering at Inspire Energy
26 June
Individual Contributors are familiar with a technical development framework that helps them with building products. Managers, especially new managers can leverage a parallel framework to help them build their teams while drawing analogies from an already familiar framework.

Viswa Mani Kiran Peddinti
Sr Engineering Manager at Instacart
13 June
Roland Fiala, Senior Vice President of Engineering at Productsup, raises an interesting issue about autonomy in teams: does it hinder collaboration opportunities that lead to better problem-solving? He shares his system for promoting teamwork in engineering departments.

Roland Fiala
Senior Vice President of Engineering at Usergems
13 June
Roland Fiala, Senior Vice President of Engineering at Productsup, highlights the importance of soft skills and shares how he motivates his engineers to further their careers by focusing on personal growth.

Roland Fiala
Senior Vice President of Engineering at Usergems