Providing Support Through Excellent Documentation
14 October, 2021
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.
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.
- 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.
Scale your coaching effort for your engineering and product teams
Develop yourself to become a stronger engineering / product leader
A major sign of trust, comfortability, and vulnerability is for someone you lead to be able to say something sucks.
Senior Engineering Manager at Curology
Jonathan Ducharme, Engineering Manager at AlleyCorp Nord, encourages the importance of a workplace environment that cultivates mental wellness.
Engineering Manager at AlleyCorp Nord
No online tool will address your team's ability to connect, collaborate, and deliver results if the individuals don't bring the right mindset to work.
CTO at REAL Engagement & Loyalty
Tarek Mehrez, Engineering Manager at Klarna, explains what team health entails and shares his advice to managers who want to assess and better their teams.
Engineering Manager at Klarna
Tommy Morgan, VP Engineering at Crystal Knows, recalls a time in his career when his values didn’t align with his superiors and shares his insights on preventing this outcome when taking on a new role.
VP Engineering at Crystal Knows