shekhargulati

Minimal Technical Documentation Every Project Should Have

In the last few months I have given a lot of thought on the minimal technical documentation that all projects should have. I consider it essential to building a quick understanding of the project and quickly onboard new developers. These documents should be maintained in the version control just like the code. The technical documentation should sit in the same version control repository as your code.

If your system is built using Microservices architecture and you use repo per service approach then it will be better to have one repository only for documentation. I prefer monorepo over repo per service. You can read more about Monorepo in a blog post I wrote earlier.

The documents that I consider essential are:

README.md
architecture.md
api.md

Software Architecture Document Template

Below is the template that I use to document software architecture. This is based on the experience I gained doing architecture and design work over the years.

If you prefer Google Docs then you can create a copy of the template. If you prefer Markdown version then you get it from the Github repository.

My Notes on the “A Philosophy of Software Design” Book

This week I finished reading A Philosophy of Software Design book by John Ousterhout. I found the book easy to read and moderately thought provoking.

The book talks about two approaches to reduce complexity of software systems – 1) embracing simplicity 2) embracing modular design.

Complexity is anything related to the structure of a software system that makes it hard to understand and modify the system.

We know we are working with a complex software system when:

Questions to ask when making Build versus Buy decision

Most software companies have to make decisions on whether to build a custom software or buy it from a vendor. Some of these decisions are mentioned below.

Should we build the recruitment tracking system or buy it?
Should we build a custom video KYC solution or buy an existing one?
Should we build a custom CRM or buy it?
Should we build a custom CMS or buy it?
Should we run your own CI server or use a cloud service like CircleCI?
Should we build our search engine using Solr or Elastic search or use a service like Algolia?

Questions To Ask When Choosing a Programming Language

This week I had a discussion with one of my friends on how to choose a programming language. It was triggered by multiple discussions I had with our customers on their engineering strategy in the last six months and one question that came multiple times was should we use X programming language for our new initiatives. Some customers were thinking of moving from .NET stack to Java, some banks were thinking about moving to Golang because their technical leaders have watched Monzo talks on Golang, for some it was from Java to Kotlin, and some were thinking of dumping JavaScript for Typescript.

To come up with the answer I try to find answers to following questions in context of the organization:

Being Chief Technology Officer: Lessons learned in my first year

Happy New Year!
2020 was a difficult year for most of us, as we fought with COVID-19 and came to terms with the remote way of working. It was a year when we had a lot more time in our hands as all of us were locked in our houses with almost no travel. The things that we took for granted were taken from us and there was a constant fear of losing the loved ones.
I hope in 2021 we regain our freedom to live freely. But, this time with a sense of responsibility and awareness.

It is now little over a year since I became Chief Technology Officer (CTO) in my current organization. And, I thought it will be a good time to do a quick retrospective on the lessons learned in my first year as CTO. The journey has been tough but deeply rewarding for me. There were occasions when I thought the leadership role was not for me and I should go back to being an individual contributor. But, with support from my organization and learning (books, blogs, observation), I have started to enjoy the role and its challenges.

Before I talk about the lessons I learned, let’s look at my software engineering journey.

My Notes on Deep Work Book

I decided to spend year-end holiday time reading a couple of books. I like to read books that in some way help me solve problems that I face in professional and personal life. At work because of my title and circumstances I have to play three different roles – maker, manager, multiplier.

Maker: Create stuff (software, powerpoint, design document, etc).
Manager: Talk to people about their concerns and hopefully resolve them or at least guide them in the direction that takes them on the resolution path. Keep the stuff moving.
Multiplier. Enabling people by helping them in software design, code reviews, estimates, hiring right people, etc.

I am fortunate that I get to work on many tasks that are cognitively demanding. At the same time, I also have to work on tasks that don’t demand such cognitive skills.

Defining Your Engineering Team Principles

In my current role as Chief Technology Officer (CTO), I am responsible for the engineering quality of our software delivery teams. We are an IT service organization where every now and then, we get to work with different kinds of customers in different domains and each at a different maturity level in software delivery.

One thing that I often struggle with is how to unite the individual engineering teams working for different customers with a common shared belief system that is actionable, pragmatic, and less abstract.

You may ask, isn’t that what organization values stand for? Before we answer, let’s define the three common terms: Values, Principles, and Practices.

On Mediocrity

In the last couple of years, one question that I have been often pondering is—

why it is difficult for senior leaders of an organization to work in unison and achieve great things together. While there are organizations that accomplish amazing things one after another, there are many others, where leaders cannot think beyond themselves and their self-interests.

The failure, in context of the blog, is not about an organization failing financially or collapsing in terms of business. An organization can be successful yet fail to achieve great things. This is a story that I have seen, read and observed, over the years. A new senior leader joins or an existing employee is promoted to a leadership role. They want to bring positive changes (at least they think that way) and become messiah for the organization. After a couple of years, there are only little achievements to be shown, nothing big and transformative that may have been realized or accomplished.

Using Testcontainters with Kotlin Spring Boot App

In this quick post I will show you how to use Testcontainers with Kotlin Spring Boot app. Testcontainers is a Java library that you can use to write integration tests that work with real third-party services like databases, message queues like Kafka, or any other service that can be packaged as a Docker container image.

Most developers use in-memory databases or fakes to test with external dependencies but to test against real stack you need to use real services. This week I faced as issue where one of my test was failing because a MySQL function was unavailable in H2. I was using in-memory H2 database in tests. My application used MySQL in the production mode. So, my valid MySQL query was not working when run in a test. This made me think of replacing H2 with MySQL database for tests.

I was aware of Testcontainers but had never used it in any application. So, this was the first time I used it. For most parts I liked it. I don’t have to work around limitations of H2 and I can hope I will not discover any issues because of difference between H2 and MySQL. Testcontainers is not perfect. It makes test slow. My build time has increased from 6 mins to 9 mins just because of Testcontainers. I am relying more on my CI server to run the complete test suite.

Testcontainers can do much more than running databases. You can use Testcontainers for:

Stream processing solutions like Apache Kafka and Apache Pulsar
AWS Localstack
Selenium tests
Chaos tests