Providing Support Through Excellent Documentation

Lyle Kozloff

Director of Support Engineering at GitLab



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.

Be notified about next articles from Lyle Kozloff

Lyle Kozloff

Director of Support Engineering at GitLab

CommunicationOrganizational StrategyCulture Development

Connect and Learn with the Best Eng Leaders

We will send you a weekly newsletter with new mentors, circles, peer groups, content, webinars,bounties and free events.


HomeCircles1-on-1 MentorshipBounties

© 2024 Plato. All rights reserved

LoginSign up