Back to resources

Providing Support Through Excellent Documentation

Remote
Company Culture

14 October, 2021

Lyle Kozloff
Lyle Kozloff

Director of Support, Global Readiness at GitLab Inc.

Lyle Kozloff, Senior Support Engineering Manager at GitLab, leads the way through a robust and comprehensive operations handbook that walks the employees through every possible scenario.

Problem

Working remotely requires a disciplined set of conventions to make sure that everyone is on the same page. Communication is hard. When you add the complexities of multiple time zones and working schedules, finding the right person who has the answer becomes increasingly challenging. A key way that my company has solved this problem is through a massive single source of truth that documents every aspect of life at the company.

I work for a company that has been operating remotely since its founding. The person who started the open-source project is from Ukraine, and the one who founded the company behind it is from the Netherlands. Because of distance, they learned to work remotely very early on.

The culture that has allowed us to thrive in these circumstances has always been centered around a living handbook that documents everything worth writing down. When I say everything, I mean everything. We have (or have had) pages on everything from the CEOs seat preferences on flights (aisle seat, economy plus for the extra legroom) to the more banal “how to book PTO”. Coming into a culture where that’s the expectation, I’ve gotten really good about being a diligent documentarian for all types of workflows within the company and my department.

More than just writing everything down though, employees are encouraged to suggest improvements and update procedures. This means that not only do we have a single source of truth, but that it’s being continuously improved by the individuals who interact with it daily.

Actions taken

Great documentation states the problem to be solved clearly. It then walks you through what you can do about it. By itself though, this isn’t enough. It’s important that folks going through that documentation are empowered to ask why and have the ability to affect change by modifying policies and procedures that don’t (or no longer) make sense.

When a process is not explained well enough, the person who encountered the problem must be able to take what they’ve learned and improve the documentation for the next person.

It’s also important to document why. One of the pages I’m proudest of in the Support section of the handbook is our Philosophy page. We don’t just have the hard-boiled workflows that describe how to handle specific ticket types, but we took the time to write down some thoughts about why we do things the way we do. Thinking through, and inviting others to join you in thinking through the deeper reasons and motivations for how you do things is key in engaging your staff.

All of these things are what have allowed us to manage a globally-distributed team effectively. Our support team alone has one hundred and thirty team members in thirty different countries. This is only half of the nations that are represented in our ranks throughout the entire company.

Documentation should be both thorough and able to get the point across to any type of person. It should also be centralized, discoverable and updateable. Without these defined pathways of communication, everything that we do would be much more difficult.

Lessons learned

  • What attracted me to this way of working was how clear it was, even for things like onboarding. I was literally able to “onboard” myself before I even started interviewing at the company, just by going through the public materials in the company handbook. Having everything publicly documented meant that I was able to ask great questions when the time actually came to begin discussing a potential future there.
  • Beyond the handbook, when in doubt: assume async consumption and write everything down. Every meeting has an agenda. Every agenda can be modified in real-time or after the fact.
  • There are few things that cannot be documented publicly, and by documenting publicly you get some unexpected benefits. Interviewing and recruitment, for example. As a result of having a public handbook, I get a lot of interesting data from the types of questions I get from people who have spent time answering their own basic questions in our documentation.

Discover Plato

Scale your coaching effort for your engineering and product teams
Develop yourself to become a stronger engineering / product leader


Related stories

Managing remote first organization

4 January

I was hired at HUMAN in 2021 to manage a team that went from hybrid to completely remote working environment because of COVID.

Building A Team
Company Culture
Ahsan Habib

Ahsan Habib

VP Software Engineering at human

Facebook vs. Google: 10 Contrasts for Engineering Careers

7 December

This is a brief comparison and contrast of Google and Facebook, as a place for one’s software engineering career. Both can be amazingly good places for engineering careers. But both places can be misfits for otherwise excellent engineers. This is a short differential guide. [Originally on LinkedIn]

Company Culture
Michael McNally

Michael McNally

Chief Technology Officeer at GraphStax

The Not-So-Easy Guide on How to grow and develop an Amazing A-Team

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.

Alignment
Building A Team
Company Culture
Sharing The Vision
Embracing Failures
Team Processes
Jaroslav Pantsjoha

Jaroslav Pantsjoha

Google Cloud Practice lead at Contino

How to improve engagement and retention in remote engineering teams?

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.

Remote
Company Culture
Collaboration
Motivation
Team Processes
Mrunal Kapade

Mrunal Kapade

Director of Engineering at Inspire Energy

High Performance Team in Action

13 October

A high performance team refers to “ a group of goal-focused individuals with specialized expertise and complementary skills who collaborate, innovate and produce consistently superior results.”

Managing Expectations
Building A Team
Company Culture
Feedback
Coaching / Training / Mentorship
Praveen Cheruvu

Praveen Cheruvu

Senior Software Engineering Manager at Anaplan