Killing Momentum with Good Intentions

Today's story is a story about failure on my part. One of the joys of being an engineering leader is mentoring and guiding folks towards new shared best practices, mental models, and design patterns.

One of my teams had been incrementally delivering a mission critical set of features enabling a number of improvements to enterprise account management, and they were in the home stretch. And that’s when I went in with my good intentions and threw a wrench in the works.

It took me longer than I'd like to admit to realize it, and for the team to let me know what I was doing was hurting them.

We'd been working with Phoenix LiveView to more effectively build a quality frontend user experience, and I noticed a pattern for abstracting handling delete multiple events types across LiveViews. Naturally, I wanted to help the team, and chimed in offering up that this may be a good opportunity for extraction and the establishment of a new pattern. This was exactly the wrong move.

I assumed the pattern was valid and this was the best time in place to establish it. Teams need time and proof, in the form of concrete examples, before endorsing a pattern. I came with none of that in hand, and here I was blocking the critical path.

It took two days of back and forth, miscommunication of the new pattern, and some potential extractions that didn't pan out, because I had poorly articulated them and left them for someone else. Finally, someone voiced frustration with the process, which pulled me out of my stupor and allowed me to step back and realize I was hurting the team.

Looking back, I should have created a follow-up pull request with an example of the extraction, and an architectural decision record (ADR) detailing the context around why this new pattern may be useful, how it would be used, and what it would potentially mean for us as an organization to adopt it.

So if you're trying to help the team in establishing new shared models and best practices, the question ought to be as a leader, when and how?

The answer to that is not at the point that you're doing a code review. Especially not when that code doesn't have any actual issues.

Extracting Patterns

First, because it's the key moral of the above story, pull it off of the critical path. Even if your pattern is perfect chances are it's something that will need to take some time to mature. Then enforce it at the point of code review after establishment.

So, now that you're off the critical path, you can take a step back and determine what the best path for extracting the pattern and demonstrating it is. This is going to get context specific.

Usually the first ought to be discussing the new pattern synchronously with other folks on the team. This is to make sure that you're not missing a critical piece of context that make it not viable.

Following that I like to use architecture decision records (ADRs) to document the context around why this pattern was extracted, what it's trying to solve for, and the trade-offs it makes. You may use Request For Comments RFCs instead, but regardless of the vehicle the idea is the same, to codify the point in time reasoning around this new idea.

Usually to go with the ADR I also like to publish a small example of this new pattern, and it's actual implementation. This doesn't mean I go through the entire codebase and set it up everywhere it's applicable, because we're still attempting to showcase viability for the team. Just find a single compelling instance where you can use it, and let the team weigh in.

From here it's usually a straight forward process to get the team's feedback for clarification and improvement of the pattern, and it's eventual adoption or rejection.

Wrapping Up

As for my story, I pulled the pattern off the critical path and the team was able to help me guide it to an even better solution. From there it handled not just delete events and their LiveView pubsub implementation, but also baked them into our default delete implementation allowing our entire application to listen for and take actions based on these events.

I'd love to hear more about when and how you and your team's establish patterns. Let me know via email or DM on Twitter.