creating engineering principles for your team

src: Creating Engineering Principles for your Team - Thomas Vanderstraeten - 2022-01-07

Abstract

Having core principles for engineering team can empoyer the engineers. There are already some best practices out there, like KISS, DRY, YAGNI, … but engineering teams can emphasis or create specific principles.

Having principles can accelerate debates and provide a welcome source of authority when one needs to be direct and efficient in making feedbacks.

Recommendations:

• short list of principles (⇐ 10)
• sharp and catchy, followed by a lightweight explanation
• controversial and opinionated
• speak to all intelligence
• principles are not an operation playbook
• principles are not a repository of best practices
• principles are not an architectural principles

During my time at Seraphin and Canyon, I found that defining and communicating core principles strenghtened the firepower of our engineering team. Nothing surprising to that 😅. Still, I believe there are a few tips & tricks one can apply to get principles right and ensure they’re not left to rot in the dust of a forgotten Notion page.

The what and why of engineering principles

Principles are a commonly agreed list of prescriptions that will drive the behaviour and output of the team. They define what’s acceptable and what not. They capture in a concise and explicit way the scale of values that is specific to the team, and the trade-offs that the team is hence making across values.

The word specific is important here. As engineers, we can rely on a huge body of best practices that are all principles in themselves. KISS, DRY, YAGNI…these are all powerful principles every engineer should have in mind regardless of their team, just because they are good professionals. What makes your team engineering principles valuable is how you choose to emphasise one or the other principle (you cannot have all of them, and you should ideally rank them).

Having these principles helps align the performance of the whole team and establish a common framework and vocabulary for judging the quality of behaviours and outputs.

In practice, besides the strategic alignment that it creates within the team (and with newcomers at onboarding), I have found that engineering principles are an efficient way to accelerate debates (thanks to first-principles thinking). They also provide a very welcome source of authority when one needs to be direct and efficient in making feedback / PR reviews. You can say “Can you check this part of your code against our YAGNI principle?“. No need to spend time giving more specific feedback, since the mention of the principle already carries with it a whole context and background known by all. Name-dropping principles like that also helps reinforcing them along the way.

I’ve also found it valuable to focus principles on behaviours that can be improved, so they act as gentle guardrail to steer the team to a better version of itself.

I’m ashamed to say I use authoritative arguments sometimes

How to formulate engineering principles

Principles must be formulated in a way that makes them easily absorbable by the team. Therefore:

• There should be only a short list of principles (10 is probably the max).
• Each principle should be sharp and catchy, ideally proverbial. I love to use one catchy sentence in bold, followed by a lightweight explanation (1-2 sentences). If you can make it rhyme or make it a play on words, go for it for sure!
• Principles should ideally be a bit controversial and opinionated, taking a stand against something. Aim at drawing a clear line in the sand. A good way to check if a principle is controversial is to take its exact opposite: if the exact opposite is abundantly absurd, the principle is probably too consensual. For example, KISS is not controversial, because its contrary is “Keep it very smart and complex”, which we know intuitively doesn’t make sense. At the contrary, the opposite of DRY is valid in case you need to go fast and avoid premature refacto (see this article for example). The same can be said for “Prefer boring tech”, because in deep-tech companies it is explicitly necessary to go for shiny new things.
• Principles should speak to all intelligences. Don’t hesitate to prefix each principle with an emoji for visual thinkers. Use concrete (counter-)examples for practical thinkers.

A good rule of thumb for formulation: your whole list of principles should fit on a beautiful poster that you could hang on the walls of your office in a non-remote world.

What engineering principles should not be

It is tempting to use principles as a bucket to throw all guidelines at the team. However, here is what principles are likely not:

• An operations playbook: the processes that your team adheres to are best described in their playbook, with all their details. Nevertheless, it should be possible to “rebuild” your processes from first-principles thinking 🤓.
• A repository of best practices: as said earlier, there are already tons of best practices out there, and the goal of principles is to pick just some of them to drive the team.
• Architectural principles: principles should describe how your team works, not what it produces. For example, stating “We prefer a majestic monolith over microservices” is an architectural principle, whereas “We use boring and plain tech” is an engineering principle that can lead to this architectural decision.

How to publish engineering principles

Once you’ve defined principles with your team, make sure that these are relentlessly exposed to everyone. I have found that the following worked well:

• One simple Notion page with the list of principles as callouts, nested in the top-level board of the Engineering team.
• From each principle, a link to a more in-depth explanation of why this principle matters (the best of the best is to have a different member of your team write out each piece for greater ownership).
• When doing PR reviews / comments in the issues tracker and invoking a principle, do take the time to link to its explanation to reinforce it.
• At Seraphin, we even built a simple Slack bot that would randomly select a principle and post it in our engineering channel every now and then as a kind reminder to the team.
• If you are in a non-remote setup, print them out on a poster, literally.

Basically, try to evangelize and reinforce principles at every occasion. You’ll know you are in good shape when devs start dropping principles explicitly during peer programming sessions or discussions on specs or course of action.

Engineering principles: an example

With that being said, here’s an example we used at Canyon. These principles are extremely focused on speed of delivery, because that is what mattered most to the entire company at the time. Also, they are intended at a senior team that has already absorbed a ton of content-related best practices before.

As you can see, these principles talk a lot about the process, but they don’t exactly define it: we leave this to the playbooks. One could argue that explicitly naming kanban columns in these principles is already too detailed - I leave it up for debate. Note that here there is only one specific deep-dive which is on E2E visibility, that I have extracted in a dedicated blog post on the topic.

The engineering principles from Canyon, focused on delivery

Engineering principles at scale

All these reflections are based on my humble personal experience managing teams of developers in 0-to-1 and 1-to-Series A startups, plus a trove of readings and podcasts along the way. I think the principles outlined in this article (principles about principles - this is getting a bit meta 👾) still apply at scale, with a few tweaks:

• As the engineering organization matures and the number of teams grows, leadership should state global principles (akin to company culture, but at engineering organization scale) that each team should translate in their own sets of principles. For example, the “We Revere Ownership” principle applies differently for a product developer (there “ownership” translates to “I will autonomously strive to get the issue moving to production, making sure it helps the user”) than for a DevOps/SRE engineer (there it will translate to “I will make this production issue my own and will not let the team down”).
• As the developers themselves grow in seniority along the journey, some principles will get completely embedded in their day-to-day behaviour, and it become so natural it won’t be needed to state them again (except in a repository of best practices). Then comes the time to look out for the next improvement areas, and define principles that will propel the team to its next evolution.

Conclusion

I’m still relatively early in my engineering career, and looking forward to taking a step back in a few years after more experiences from the battlefield. Hopefully these tips with help you as much as they helped me. Thanks for reading and don’t hesitate to reach out to me on Twitter. Also, if you are a CTO, EM or tech leader at large, do check out RM-RF, my Substack about crazy dev stories. Cheers!