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

Team Development Framework for new managers

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.

Building A Team
Team Processes
New Manager
Viswa Mani Kiran Peddinti

Viswa Mani Kiran Peddinti

Sr Engineering Manager at Instacart

Promoting Interdepartmental Teamwork for More Efficient Problem-Solving

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.

Internal Communication
Collaboration
Roadmap
Team Processes
Cross-Functional Collaboration
Roland Fiala

Roland Fiala

Senior Vice President of Engineering at Usergems

How to Motivate Your Engineers to Grow in Their Careers

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.

Goal Setting
Different Skillsets
Handling Promotion
Personal Growth
Coaching / Training / Mentorship
Motivation
Team Processes
Career Path
Performance
Roland Fiala

Roland Fiala

Senior Vice President of Engineering at Usergems

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

Technical Program Management 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