A small grocery list of good values 🔗
Write down a small check list of values, qualities or features that matter to your project. The list can vary between projects because, the time, scope, complexity, target audience and your own experience vary.
- Do you want straightforward configuration for your project? Note it down as a value.
- Want to make the system friendly to day two operations? Put it in words.
- You are only targeting to serve a certain known scale? This goes in the list.
This gives clarity on what you want to achieve. It helps eliminate things that are not important and relieves you of even wondering about the unnecessary.
Most importantly, this becomes the foundation of theory building1 that’s very important for building correct systems. It will help shaping the architecture, nudging you on the right direction like the north star.
Trying to achieve some of the values may introduce some not-so-desirable qualities as well. For example, a push to make the configuration simple may push the complexity into code (Because Complexity has to live somewhere2). But you are now empowered to consciously weigh the pros and cons and make the right decision based on context.
Pick a good naming convention. Stick to it. 🔗
Sounds very simple right? Wrong! in my experience, both of these are incredibly hard in practice. There are good model naming conventions out there. But picking one and making it fit to your requirements will take some time. This feels like a waste of time at face value. It’s “just” a naming convention after all. Also, if you are in a team larger than a handful of people, consensus gets harder. Add even one more group of people, no matter how small, to the mix and things can get pretty close to hopeless.
A mature, strong senior manager can be really helpful getting through this. Also, when you don’t see progress and it appears no one really cares, be the adult in the room, pick one based best of your judgement, document it and move on (Trust me on this!).
The documenting part is very VERY important. You need to put the news about the convention in the faces of everyone involved. Make it easy to find, and easy to follow. Otherwise there’s no hope of sticking to it.
Also, it’s OK to be a bit zealous about it. This communicates the importance of it.
Small throwaway prototypes 🔗
These are to help me get to the right feel of the system. Even the small things like how does your naming convention end up looking like in the dashboard (Console) matter in the overall experience.
Can I make the names look more intuitive and contextualised? Can I make this bit of configuration less repetitive, or more intuitive? Can I do away with this bit of configuration and provide better defaults? Could I provide the user more flexibility for future/day 2 changes?
Small prototypes is the way I actively explore these ideas to get to a better state of things.
Make testing dead easy 🔗
Testing can notoriously be difficult achieve in infrastructure projects. Yet it has to be done and people will try and do their best. But the best becomes subjective and restrictive systems, prohibitive deadlines can force worse versions of targeted “best”.
For example, with Terraform having long running test infrastructure and applying only the new changes on top it it is not the best. It’s what people settle for, when testing is hard.
Hence it’s very important to make testing easy and accessible to all contributing to the system.
I have done work that drastically simplified and ‘democratised’ testing, it started catching bugs that were not even related to the section I worked on. (ex: I spotted other people’s bugs when I figured out dead simple testing).
Easy testing also improves ability to do small, quick prototypes and test out ideas. A huge push to improving quality.
PS: I wrote this on 2025-11-23 and had it in a private knwoledge base only a few friends have access to. I intended to move it here after feedback from friends. And eventually I got around to it, felt it’s alright on a second read. These are just some generic advice based on my experience in my last employment. More specific details about the related project is found here at my Notes Site
Thanks Alex for the first read and feecback!