Design

Although it was years ago, I still remember the conversation vividly. I was having my regular check-in with the CTO. It was also sunny outside, and the view from his office was particularly nice that day.

He asked me, “Is our app scalable?” After a moment of thought, I answered, “Yes.”

I spent the next few years remembering that conversation, wondering what would have happened if I had asked what he meant by scalable.

I have been trying to improve the organization of my household for years. My wife and I have been using shared Google calendars for over a decade, but there are plenty of issues we could still improve. It was only minor challenges when it was just the two of us, but once we had a child, the systems we had started to show their limits.

I quit my job with the dream of building my own product, but I started without any particular ideas about what to build. It didn’t take long before I was considering working on this exact problem. Not only was it something I would benefit from, but it was also something I would find interesting, and could enjoy building and maintaining by myself.

I have always liked using whiteboards. They are a great tool for communicating, but also great for exploring thoughts and stimulating creativity. There are computerized equivalents, and they have their advantages, but I’ve never found them as effective because I get distracted too easily. I can spend more time fiddling with the lines and colours than working on my actual problem.

I like whiteboards so much that I bought a stack of them, and an artist’s portfolio bag to carry them around. I imagined popping out a few drawings at a meeting, or handing boards around for a creative session. I still love the idea, but in more than twenty years I’ve never even taken them out of the house.

I recently launched my new company, Pragmatic Potato Software Inc. The creation of a company itself is pretty easy, but setting up everything you need to do business can become overwhelming quickly. There are a lot of compelling options available, each promising the moon. It’s not that simple though.

I’m going to be writing about the technology stack I’m using to run my company, and why I made the choices I did. There is a lot more to a company than its technology, but I’m not an expert in setting those up.

One often (and ironically) repeated rule in programming is: don’t repeat yourself. We repeat it so much we even have an abbreviation: DRY. There are good reasons for this advice. Duplicating and modifying code can be a quick and easy way to get a feature done, but it can also lead to problems over time. It’s harder to understand code when the valuable logic is mixed with reams of low-value boilerplate. Subtle differences can also sneak in, leading to inconsistent behaviour across the application. Things get even more difficult if you want to make a change.

I used to use Getform for a contact form on my consulting company website. I recently received an email from them announcing that their free tier was dropping from 50 submissions per month to a lifetime limit of 25. This makes it useless for anything more than a trial, and their lowest tier is a more expensive than other similar options.

I’m not here to complain about companies taking back free offerings. I don’t like the change, and I wish they’d given me more than three days of notice, but they are a businesses, and businesses need to make money. It is a good reminder though: even if something is free to use, it still takes time and effort to integrate, to maintain, and you may occasionally need to throw it out and find a replacement.

Architectural Decision Records are a simple technique that promotes good architectural thinking and better collaboration. They don’t need to be big or complicated to be effective, but they do take some time, and are yet another step between setting goals and delivering value. If you use them in the right circumstances they can be a big help.

What is an Architectural Decision Record?

An Architectural Decision Record (often abbreviated ADR) is just as the name implies: a document that describes an architectural decision. It can include various details, but should at a minimum describe the problem being solved and the solution that was chosen. It can be a simple text document with a page or two of text, or it can be longer with specific sections that are important to the team.

Building software is a mostly creative endeavour, and as such, it sometimes resists progress. No matter how hard you try to push forward, if you are truly stuck, continuing on the same path is unlikely to work. Fortunately, there are a few different tricks you can use to get going again.

Take a rest

The easiest way I’ve found to get back on track is to take a break. When in the office this was often making a cup of tea or eating a snack in the break room. It could have been a ten-minute walk around the block, but if I’m honest, I have rarely tried this.

A junior developer needs to strengthen their technical skills to advance. An intermediate developer needs to strengthen their organizational skills to advance. Senior developers need to master these and also demonstrate that they can move multiple teams forward together. Influencing people (and especially developers) is no easy task, but a positive reputation can do a lot of the heavy lifting. One of the easiest ways to amplify your reputation is to put some extra effort in when choosing a name.

As an architect I’ve been asked to answer a lot of hard questions. I used to waste time figuring out how to structure my answers, preventing me from getting into a good flow sooner. Now I have a simple template that is easy to use, easy to read, and saves me that wasted time up front.

This template works for simple reports that are only a couple of pages, but can easily be adjusted or expanded for more complicated or much larger documents.