Back to resources

The Benefits of Documentation

Team Processes

18 March, 2021

Justin Zhang
Justin Zhang

Sr. Director of Engineering at CertiK

Justin Zhang, Engineering Manager at Convoy, highlights all the benefits of documentation while also adding why cultivating a culture of documentation in a remote context is particularly critical today.

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

Streamlining Product Processes After a Reorganization

16 May

Snehal Shaha, Lead Technical Program Manager at Momentive (fka SurveyMonkey), details her short-term technical strategy to unify processes among teams following an acquisition.

Acquisition / Integration
Product Team
Product
Building A Team
Leadership
Internal Communication
Collaboration
Reorganization
Strategy
Team Processes
Cross-Functional Collaboration
Snehal Shaha

Snehal Shaha

Senior EPM/TPM at Apple Inc.

The Optimization and Organization of Large Scale Demand

4 May

Kamal Qadri, Senior Manager at FICO, drives the importance of setting expectations when optimizing large-scale requirements.

Managing Expectations
Delegate
Team Processes
Prioritization
Kamal Qadri

Kamal Qadri

Head of Software Quality Assurance at FICO

Why Documentation Is the Key to Success

6 April

Henning Muszynski, Head of Frontend at Doist, promotes his ideas on how documentation ensures consistency, efficiency, and standardization.

Alignment
Collaboration
Productivity
Hiring
Team Processes
Henning Muszynski

Henning Muszynski

Head of Frontend at Doist

It's Time to Say 'No' to Manual Business Processes

6 April

Henning Muszynski, Head of Frontend at Doist, talks about the cost of slow and arduous processes that add up over time and how to bring the changes systematically.

Changing A Company
Conflict Solving
Internal Communication
Feedback
Team Processes
Henning Muszynski

Henning Muszynski

Head of Frontend at Doist

Typical Challenge of Scaling Teams: What to Do When Your Process Doesn’t Scale

30 March

Christophe Broult, Director of Test Engineering at diconium, focuses on how he scaled his team while building organization and management teams in place.

Scaling Team
Building A Team
Reorganization
Team Processes
Christophe Broult

Christophe Broult

Director Test Engineering at diconium

You're a great engineer.
Become a great engineering leader.

Plato (platohq.com) is the world's biggest mentorship platform for engineering managers & product managers. We've curated a community of mentors who are the tech industry's best engineering & product leaders from companies like Facebook, Lyft, Slack, Airbnb, Gusto, and more.