Plato Elevate Winter Summit has been announced (Dec 7th-8th)

🔥

Back to resources

The Benefits of Documentation

Team Processes

18 March, 2021

Justin Zhang
Justin Zhang

Engineering Manager at Convoy Inc

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

Building a New Team in a Foreign Country

23 November

Adam Hawkins, Site Reliability Engineer at Skillshare, went all the way across the world to build a brand new team who worked very differently than he was used to.

Team Processes
Adam Hawkins

Adam Hawkins

Site Reliability Engineer at Skillshare

What It Takes to Understand Other’s Perspective

23 November

Nicholas Cheever, Divisional Vice President, Global Supply Chain Technology at Trimble Transportation, shares how to really understand someone else’s point of view.

Team Processes
Nicholas Cheever

Nicholas Cheever

Divisional Vice President, Global Supply Chain Technology at Trimble Transportation

How to Handle Team Collaboration After a Merger?

23 November

Nicholas Cheever, Divisional Vice President, Global Supply Chain Technology at Trimble Transportation, shares how he helped the acquired company’s team members understand the business mission and give them focus.

Acquisition / Integration
Team Processes
Nicholas Cheever

Nicholas Cheever

Divisional Vice President, Global Supply Chain Technology at Trimble Transportation

Surefire Ways to Boost Team Morale

11 November

Rajesh Agarwal, VP & Head of Engineering at Syncro, talks about effective ways to boost team morale when stepping in as a new manager in the team.

Motivation
Team Processes
Rajesh Agarwal

Rajesh Agarwal

VP and Head of Engineering at Syncro

How an Empathetic Approach Can Solve Problems

10 November

Han Wang, Director of Engineering at Sonder Inc., shares how he changed a manager’s viewpoint for achieving better results and improved team coordination.

Goal Setting
Personal Growth
Leadership
Coaching / Training / Mentorship
Team Processes
Han Wang

Han Wang

Director of Engineering at Sonder Inc

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.