“You are doing your design reviews wrong”

I have the privilege of working in a team in Microsoft with very talented individuals, where we help Microsoft customers to overcome technical challenges with their Azure deployments. One of the most common engagements that we do for organizations using Azure is helping them to verify that their Azure designs fulfill their functional and non-functional requirements, and that they adhere to Microsoft best practices.

We were working remotely even before the current pandemic, which has many implications. For example, it is very easy getting two engineers in the same call. Interestingly enough, I had the pleasure to codeliver one of those design reviews with one of my talented colleagues some years ago, who after the call kindly let me know that I had forgotten to check a couple of design points regarding application deployment.

My colleague was completely right, my own background on infrastructure did bias the way I reviewed Azure designs, unconsciously making me focus on certain aspects and ignoring others. So we created some “checklists”, so that engineers like me would not forget to consider any critical design areas of an architecture, thus opening our eyes to our own potential technology blind spots.

We wrote those “checklists” in Excel, which was ideal to share with our customers and partners after the review exercise. However, Excel has a fundamental problem: it is very difficult to version-control it with modern tools such as git.

What did we do?

We decided to split the review content in two: we would keep Excel as frontend, but the actual elements of the checklist would be text-based, checked in Github (https://github.com/Azure/review-checklists):

In the repo you have a blank spreadsheet, that includes some VBA macros (yeah, mixing cool stuff like Github actions with “prehistoric” tools like VBA!). When you open the spreadsheet, there are a couple of dropdown lists where you can select which technology and language you want to load, which allows to get the latest JSON-based checklist from Github:

The spreadsheet is a simple sequence of things to think about when reviewing a certain design. It doesn’t mean that you need to do everything exactly as Microsoft best practices dictate, since design decisions are always compromises between different disciplines often pulling in opposite directions (security, cost, simplicity, etc).

What have we learnt?

In this exercise we have found out that having Github as version control mechanism allowed for a much better collaboration across different engineers, thus dumping our collective knowledge into this single repository of information.

Other advantages include automatic translation in other languages using Azure Translator and the Github action in https://github.com/IEvangelist/resource-translator, since we help organizations all over the world. Today we are translating into Spanish, Brazilian Portuguese, Japanese and Korean.

But in my opinion, the most important benefit is being able to share our best practices with the much broader community out there of Azure experts, that can leverage our experience and at the same time contribute back, so that others can benefit from their knowledge.

What are we thinking about?

Probably as you are reading this you are thinking that we could do so much more with this content: replacing Excel with a web frontend, automatically discovering and analyzing existing environments, or more. Please let us know your ideas by sending issues to the repository. Thanks for reading!