The Case for Consistent Documentation

(Or, How to Leave a Client in 10 Days)

Words can't begin to express the anxiety I felt leaving my first job last spring. I'd been at the company for just under two years and felt an immense amount of loyalty to the team. (I think something about them hiring me as a junior engineer without experience made me feel indebted to them, even years down the line.) As I put in my notice, a question kept nagging me: how could I wrap up two years in two weeks?

What did leaving this company powerfully even look like? Making as much progress on our backlog as possible while I could? Or just doing exactly what I'd been doing for the past two years until the clock ran out? Would any of these approaches put them in a better position? Probably not.

I decided that, for me, a powerful departure meant slowing down. It meant giving myself and my co-workers closure. It meant transferring domain knowledge to the newer team members. It meant leaving open space on my calendar for any questions or chats that might arise. It meant writing zero code and a ton of documentation. The process was uncomfortable, but when 5 PM came on my last Friday, I knew I'd used my time wisely and I felt fully available to start my next position.

While I had succeeded in making a graceful departure in this instance, I began to think about the future. I certainly wasn't done leaving projects in my career. The questions I was left with included: How could I avoid getting caught off guard by the next inevitable exit? And, how could I begin to craft a formulae for seamless transitions?

One Foot Out the Door

These questions got me thinking about the transient nature of not only consulting projects, but also engineering engagements of all shapes and sizes. Now a year into working at Formidable, I'm more comfortable with the concept of leaving—it's fundamental to what we do as consultants. The advice I would have given myself at the beginning of my career is this: You should approach any project knowing that it's temporary. It's not an exaggeration to say that this is the last thing fresh-out-of-bootcamp-, no-production-experience-, I-swear-I-can-code- me would have wanted to hear. All I wanted was to feel comfortable and to know a codebase intimately enough to do what was asked of me. The idea of having to learn a codebase knowing I wouldn't be there long would have felt futile at best. And now, that's the epitome of my job. Funny how life works.

So at the beginning of any project, I think about the end.

The good news is this: I've found that it's not as daunting as it sounds. When I approach client projects as guaranteed temporary engagements, I feel empowered to make the leaving process so much less chaotic (and, I would argue, this philosophy makes my time on the project much more impactful). So at the beginning of any project, I think about the end. I think about what leaving this project will be like for me, and what onboarding this project will be like for the next engineer after I'm gone. I think about what kind of influence I can have on this client during the limited amount of time I'm here. I think about the problem, knowing with near certainty that I won't be there to see it entirely solved, but that I can make an impact nonetheless. If I've lost you and you're thinking, "This isn't how to leave a client, it's how to be on a client," I'd argue it's one and the same—and that's the whole point.

The Recipe

I frame every client engagement in roughly the same way. First, and arguably most importantly, I make a Notion page for my personal documentation of the client (what lives in here will be covered in the next few points).

The Onboarding Process

When I join a team, I first ask for written documentation. As I go through it, I take note of any questions that arise:

• Does it include a list of the team members and their roles and locations?
• Does it provide links to all codebases/ticket tracking systems/designs?
• Do I understand the team's objectives for the next 12-18 months and what phase of the project we're currently in?
• Do I understand how we, the consultants, fit into the mix? Is our contract for another six months? A year? Do they have specific objective they would like us to meet, or do they just need some help getting on track?

I schedule a meeting with the team lead immediately after, where I usually get those questions answered pretty quickly. The key here is that I don't delete my questions. Even if I don't have the time at that moment to update the official documentation myself, I keep track of what was unclear and the answers that I had to dig around to find. This all goes into my personal page.

Contributing & Tracking Work

As I receive work, I push for tickets to include all necessary context—even if I've had conversations outside of the ticket for clarification, even if I have to add it myself. Likewise, when I create a PR, I leave nothing to the imagination. I do my best to include all relevant links (tickets, designs, related PRs) and leave comments throughout the code regarding why I've made the changes and any downstream effects they might incur.

• Note - This isn't overkill. This is history being written. Leaving super-detailed PRs is A) a timesaver and general courtesy for those who review your PRs, B) a great way to document your thought process at that point in time should currently held assumptions change, and C) a sweet way to introduce future team members to the multitude of factors they should consider when contributing to this codebase.
• If it becomes clear that this is work that is commonly performed, I link the PR in my personal page. It's a quick reference for me if I'm asked to repeat the task later on, and a great way to build context around our processes for a future new team member.

Understanding the Full Scope

I try to understand the larger problem fully, knowing I probably won't be there to fully solve it. Even if our engagement with the client is six months, understanding their 12-month objectives allows us to make recommendations that reflect and empower their long term goals. For example, if we understand that the client's end goal is X, and we're being asked to implement Y as a step toward X, but we know that Z is a better fit, we shouldn't just go forth and implement Y in a vacuum. Or maybe we should, but we should definitely provide this insight to the client so they understand the long-term implications. Sometimes the strongest impact you can have on a client isn't the code you write, it's the direction you provide and the processes you enhance. That being said, code is pretty sweet too.

Sometimes the strongest impact you can have on a client isn't the code you write, it's the direction you provide and the processes you enhance.

Slowing Down

When I know my time at a client is ending, as I did in my last job, I focus on slowing down and leaving powerfully. Overwhelmingly, this equates to writing documentation. Luckily, I have a resource to draw from: I've been writing my personal documentation the whole time. In the end, I know exactly how I felt at the beginning—because in the beginning, I was thinking about the end.

Perfect Impermanence

So how do you leave a job in 10 days? Maybe the answer is you don't. You lean into the impermanence and leave it the whole time. Whether it's a consulting job, product company, or anything in between, we, as engineers will almost certainly not stay on the same team/project/codebase forever. In the meantime, we do ourselves and our teammates a service by ensuring that the past is documented and every aspect of the project is approached with the future in mind.