👉 Simple Frameworks to Document Your Software Architecture

The Tech Caffeine #42: This Week in Tech

May 13, 2022

I hope you're enjoying "The Tech Caffeine." I would appreciate it if you passed this along to a friend.

👉 Top Five

1️⃣ Writing is hard. As a senior software engineer, the chances are that writing is the most important skill you have to acquire to increase your scope beyond the team and advance your career. If you are looking for some great advice, then here you go - Writing for Engineers

2️⃣ Preventing burnout: A manager's toolkit - In this post, GitLab co-founder and CEO Sid Sijbrandij and Michelle Hodges, vice president of Global Channels, discussed how managers could support their team members and help prevent burnout.

3️⃣ End-to-end machine learning solution on PostgresSQL - Is there anything Postgres can’t do? 😉

4️⃣ MongoDB CTO on (no)SQL, Superapps, and Southeast Asia - In this interview, Mark Porter shares his views on the thawing relationship between software vendors and cloud providers and why there’s still a big business in selling installed software.

5️⃣ One of the ways that Amazon makes online shopping more convenient for customers is by caching the results of popular product queries. In a paper we presented last week at the Web Conference, Amazon describes a technique for using cache space more efficiently by storing only one descriptor of every product. - More-efficient caching for product retrieval

Do you write RESTful APIs? Check out these design best practices - RESTful API Design — Step By Step Guide.

🤿 The Deep Dive

Simple Frameworks to Document Your Software Architecture

When asked how they document their software architecture, many software teams will refer to a diagram with lines and boxes. The boxes and lines might work in some cases, but not every time.

A Good software architecture document should help software teams communicate internally and externally.

It should provide the systems context, participating components, technologies used, and why certain choices were made over the others.

In the quest to know more, I started asking around -

Some mentioned the tool they use, while others focused on how they store the documents. I wanted to know if they use any kind of format/template/framework to capture the system's architecture.

After doing detailed research, I gained some helpful insights. In this post, I am sharing some techniques that you might find useful.

C4 Model

The C4 model was mentioned as an obvious choice since it provides just enough information for the different audiences of the document.

If you use boxes and lines, you tend to focus either on System Context, Technologies, Deployment, etc. The model ensures that all levels of details are captured.

Adopting the C4 Model without changing your diagramming tool is very easy, as many tools support it.

You can read about the C4 Model in detail here.

Arc42

I was directed to another good framework. Having reviewed the details, I was impressed with the coverage this template/framework captures.

As shown in the above diagram, the template consists of 12 sections, each capturing the details of various aspects of software architecture.

The Building Block view is pretty similar to what we have seen in the C4 Model.

Source - https://docs.arc42.org/images/05-building-block-hierarchy.png

The Architecture Decisions section encourages you to keep the Architecture Decision Records(ADR).

If you haven’t heard about Architecture Decision Records(ADRs), here is a recommended read - A Simple but Powerful Tool to Record Your Architectural Decisions

Overall this model looks pretty comprehensive and does a pretty good job of capturing the right details.

If you would like to adopt Arc42, don’t forget to check the tips at the bottom of each section on this site.

If you have been using some other formats/templates/frameworks, please do let me know in the comments section.