Technical Debt Scenario #1: Start without any architectural vision

Let us examine the first scenario of how technical debt can cause in a product team from day 0.

• The scenario
• What's the problem here?
• How can you prevent this problem?
• Summary

The scenario

Developer: "Let's do it! Let's write software! 💪"

🕑 Sprint 1, 2, 3

Developer: "Kubernetes, GitOps, React, Quarkus, gRPC, DDD, CQRS... hurray this greenfield approach so f***ing cool. 🙌"

🕑 Sprint 4, 5, 6

Your Product Owner: "Hey, the feature we developed in Sprint 2 is no longer working 🥴... and as you know ☝️, our future software product needs to serve 2k users at the same time, the web UI needs to be fast and able to handle many different types of users (e.g. low vision), and we need to support installation on a Windows system at our customer's site ...."

🕑  Sprint 8..10 (~ after more than a half year)

"This doesn't look good. 🥺" says an engineer to the product team after Sprint 10.

"There's a lot of tech debt here. We need to do a lot of rework. Or should we restart this initiative? 😩"

Your sponsor: 💩🔥💩🔥☠️💀👺

What's the problem here?

Product teams often forget to be aware of the constraints and context in which they are working, especially at the beginning.

What are the quality goals of the software product, what are the technical and organizational constraints? They need an architectural vision, a lighthouse that enables them to make sustainable decisions.

How can you prevent this problem?

Being able to quickly develop and demonstrate working software from scratch is great and important. But that does not stop you from getting the following important things right. If you do not clear these right in the early stages of your product development, you'll be thwarted later.

🔦 Elaborate Quality goals of the software product

Quality goals are, unfortunately, the least considered tools for reasoning about architectural decisions. Quality goals shape your technical solution - whether implicit or explicit. Each architecture decision should support at least a quality goal or a business requirement.

You see in the above scenario, the product owner says to his team that the software must be "fast". But what does "fast" mean? As a discipline of software architecture, you should help your product owner explain this. "Fast" will be a quality goal. But it's only a goal if it's measurable. How can you turn "fast" into a measurable quality goal? It's a mix of interviewing your prospective customer, putting what they say into a business context, and following best practices in a technical context. This is where quality scenarios come in. Quality scenarios help you make quality goals tangible. With the underlying quality scenario, you can easily communicate a quality goal to your product team.

So let us show a sample quality scenario for this "fast" statement.

„Order records have to load fast” (performance efficiency) 1️⃣

The user 2️⃣ finds loading and navigating through the order records smooth even on a 3G connection. Loading and rendering the order detail view in a modern browser is under 1 second 3️⃣ on a 3G connection.

As you can see in the example above, a quality goal should contain the following elements:

• 1️⃣ Speaking title for a quality goal with the link to the quality attribute
• 2️⃣ Make the persona the focus of the quality goal
• 3️⃣ Make the goal measurable (if it is possible)

📋 Understand Constraints and conventions

You should know the elementary technical, organizational or political constraints of the future software product. You don't need to write 20 pages concept. This lean structure will help you:

• Id of the identified constraint or convention
• The constraint or the convention
• The explanation for this constraint or convention

The following examples show how you can document constraints and conventions in a streamlined way. This will also help you communicate them to the entire product team.

• Id: 1
• Constraint: Usage of Java as a backend programming language
• Explanation: The company has Java engineers for backend development.

• Id: 2
• Constraint: Component has to be operable as Docker Container in Kubernetes
• Explanation: The Ops team is experienced with Docker and Kubernetes.

• Id: 3
• Constraint: If third-party software must be used, open-source software components with a large community are preferred.
• Explanation: The company supports community-driven open source software and is convinced of its sustainability

• Id: 4
• Constraint: Adoption of Scrum
• Explanation: The company does not yet know all the detailed business requirements for the product. We need an iterative and evolutionary approach to product development.

• Id: 5
• Constraint: Development Tools
• Explanation: Each developer can choose their own IDE. We use the Atlassian toolstack for issue management, source code- and build management (Jira and Bitbucket with pipelines) because it is already used in the organization.

• Id: 6
• Constraint: Language of business objects
• Explanation: As a German-speaking software company, we name the business object in German. That is, we use German when naming the database objects and in the code. In this way, we have no implicit translation of business objects and prevent misunderstandings.

• ‌Id: 7
• Constraint: Documentation of architecture decisions
• Explanation: Architecture decisions are documented as architecture decision records and versioned via Git. In this way, decisions are documented in a transparent and traceable manner.

💡 Get the context and scope

You need to know your business and your technical context. If you do not know that, you should not start programming. Understanding the business and technical context is important in order to meet business needs with your future software product.

Business context

In the business context, you should identify all communication partners. Examples of communication partners for your future software product might include specific users or IT systems that your software product will communicate with. Identify their interface in a high-level view.

Technical context

Try to work out the technical context at a macro level. This includes all the technical interfaces that connect your future product to its environment. Try to capture the business-specific inputs/outputs at the interfaces.

Summary

If you are starting with a new software product, you need to at least work out the following points that are already known:

• Quality objectives, described as quality scenarios, help you design your system based on non-functional requirements.
• Constraints and conventions, described in a lean form, preserve your playground for product development.
• The business context, which helps you identify your communication partners.
• The technical context, which helps you identify and communicate the technical interfaces.

Elaborating on the above points will give you a view to the lighthouse to start your product development in a targeted way without already building up unnecessary technical debt.

Once you have established and communicated these points, you can begin the first iterations of the implementation.

Did the information in this article add value for you? Or did you miss something? I welcome any feedback and discussion. Feel free to contact me.