The first time is never your fault
What I learned about team documentation, onboarding, and implicit rules
When I was working in consulting, my boss gave me a serious dressing down because for an entire month I had logged my hours on a client incorrectly, going over the allocated budget and causing the company to lose money.
It was a fairly tough conversation and at the time I felt incredibly guilty. I still remember it vividly because the root of the problem was that, when I was hired, no one had clearly explained what the actual rule was.
Years later, as a leader, I made the same mistake my boss had made. Maybe my reaction was a bit more measured, but I still overlooked something important in the onboarding process, and I ended up saying the very same thing that had once been said to me: «How could you not know?».
The review process within the team was shared by everyone, but it was informal. Most importantly, the tool didn’t prevent a release if there wasn’t explicit approval from at least one other team member. To me it was obvious, to the rest of the team it was too. No one had ever questioned it.
The new hire, on the other hand, pushed straight to production without even going through staging because, quite simply, that’s how things were done at their previous job. Even though their teammates had shown them the process, it never really sank in that this step was mandatory. The outcome was exactly what you’d expect.
As you’ve probably guessed, today we’re talking about team documentation and why a solid onboarding process is a long term effort rather than a one time task.
There are no “trivial” mistakes
That question we saw earlier, “How could you not know?”, became a trigger for me over time. I stopped asking it to the person in front of me and started using it as a prompt to create or update the team’s internal documentation instead.
These days I invest heavily in documentation because I learned the hard way that unwritten rules are decisions in their own right. The only problem is that someone else ends up paying the price for those decisions.
I no longer see onboarding as a standalone activity. Instead, I spend that time keeping the documentation up to date so the whole team can rely on it whenever they need to.
There’s another trigger that tells me a process, a practice, or a workflow isn’t clear even to people who were at the company before I joined: when things simply don’t get done.
In many cases, when someone doesn’t do a certain thing, it’s not about a lack of willingness. More often, it’s because they’re not clear on how it’s supposed to be done. And you don’t just see this when someone new joins. You see it in day to day work, and it’s more subtle, because people might be afraid to ask, assuming it’s their fault if they don’t know how to do something.
When someone starts winging it, gets stuck, or simply doesn’t do something you expected them to do, it may be because a piece of context exists only in your head and never actually made it into theirs.
Documentation is may be a cost
Anyone who comes from the tech world, and software development in particular, probably has a love hate relationship with documentation, both when it comes to writing it and using it. The environments I work in, or have worked in, are no different. I don’t kid myself into thinking that writing hundreds of pages of documentation will magically lead people to read everything I or someone else on the team puts together.
There is a middle ground, though. Having a clear, straightforward reference that explains how things work, who to ask for what, and so on, without fluff and straight to the point, delivers solid results. The new AI tools do the rest by making it much easier to find the information you need.
Here’s an example of the main page of the team documentation I introduced after joining a new company:
When I joined, I simply wrote down all the rules, expectations, and workflows that had been living only in the heads of the people who had been there longer, making them explicit for me but, more importantly, for them.
At that point, onboarding became little more than a set of materials pointing to an overview of the company, a few checklists covering accounts and software to set up, and clear guidance on where and who to go to for information during the first few weeks.
Another thing that made a real difference was introducing a buddy for each new joiner. It had a double benefit: on one hand, it helped newcomers get past the awkwardness of asking questions directly to their manager; on the other, it helped spread knowledge among people who were already on the team.
If you want to dive deeper into the buddy concept, a book I recommend is Onboarding: Onboarding: How to Get Your New Employees Up to Speed in Half the Time 1st Edition. Another one is Crucial Conversations. Useful as an indirect reference: the buddy is the person who creates a safe space for the difficult conversations that a new hire wouldn't dare to have with their manager.
What to do when the mistakes already happened?
No matter how much you try to prevent it, you’ll eventually find yourself in a situation where someone on your team messes up something that seemed obvious to you. What should you do in those cases?
I could call this the “Captain Obvious” section, but instead of asking the question that’s followed us throughout this post, the first thing to do is pause and ask yourself whether the responsibility might be yours rather than theirs.
The next step is to say it out loud: «You couldn’t have known, because we never explained it to you». Finally, make it actionable. Turn that implicit rule into something documented, tracked, and shared across the team.
What can you do to reduce implicit rules in your team?
I’ve tried to put together a few simple actions that can help reduce implicit rules within a team from day one, especially for new joiners.
Write down the rules you take for granted
Pay attention to the team’s behaviors, practices, and day to day actions, and document them somewhere. As you notice more of them, keep adding them to the document.
From day one, explain what costs money, time, or credibility
Identify the most critical or high impact areas and make sure they are clearly explained as soon as someone new joins the team.
Don’t wait for questions
Someone who just started doesn’t even know what they don’t know. That’s why it’s essential to be proactive and make the most important things explicit.
Keep rules simple and avoid conditional logic
When rules apply only in certain situations, it becomes hard for people to tell whether they are in the right context, and the risk of getting stuck or making mistakes increases. Minimize interpretations and limit the number of scenarios in which a rule applies.
TL;DR
When someone new on the team makes a mistake that seems obvious to you, the problem is almost never the person. The problem is what wasn’t communicated to them. And if you’re a leader, “who knew and didn’t say it” is almost always you. Good news is that you can prevent or at least mitigate this!
Credits: Illustration 1