cards42.org
The activity cards for software architects
The accompanying page to the cards42 project. This project is also available in German.
Introduction
Welcome to the cards42 project! The cards from cards42 support you in your daily work on software architecture. The cards give you short, thought-provoking impulses for difficult situations and help to shed new light on complex challenges. This website offers detailed explanations as well as the background and further information about the cards' contents.Cards
We are often trapped in our own world with all its restrictions. We are conditioned to be modest – this leads to solutions that are modest as well.
But what if you only had infinite resources (time, money, people, …)? What would you then do with your software system? What is the maximum amount of meaningful resources that still make sense? How far away are you from getting those? What valuable resources can you get your hands on today that make your software system tremendously better?
Collect the opportunities on this map and discuss them with your team!
Important quality attribute goals significantly determine decision-making in the implementation of software systems. In this quick check, you can compare your top 3 quality goals with the implemented solutions to check if they fit together.
Find out first what the top quality attribute goals are. Then identify the essential architectural approaches of your software system. These are all the technical stuff you would talk about with a tech-savvy person who wants to know how you have designed your software system. Then estimate how well the architecture approach supports (or contradicts) the fullfillment of a quality goal.
If they don’t match, double-check that your quality goals are still the right ones or if you’ve chosen the wrong approaches for your software system.
More information
- Article about Quality-Driven Software Architecture from Gernot Starke
- Evaluation method Architecture Tradeoff Analysis Method
In software systems that have been under development for a long time, it becomes challenging to understand decisions made in the past. Therefore it is essential to document decisions and their motives understandably.
With the help of Architecture Decisions Records (ADRs), it is possible to document decisions in light and consistent ways. In addition, the motivation for a decision, the thought processes that led to the decision, and the context (time, knowledge, participants, …) are recorded, too.
With this template, you could practice structuring your decisions according to the ideas of the ADRs:
- Title: What decision is at stake?
- Status: What is the status of the ADR? List rejected or obsolete ADRs!
- Context: Why decide now? What were the circumstances?
- Decision: What was the decision and what were the alternatives?
- Consequences: With which advantages and disadvantages do we want to live from now on?
More information
The day has 24h and then there is the night, too.
— A former professor of Markus.
…and suddenly the day was over. But what did you get done? This pie chart can help you see what you’ve been spending your precious time on:
- Are you using your time effectively?
- Which of the time slots can you simply get rid of?
- Are you achieving maximum utilization of your time?
Assess the time you spent! See if others determine how you work or if you have control over your own time:
- How much time do you invest in future-oriented work?
- How much time do you expend on unplanned work?
- How much time is spent on routine tasks?
More information
- Take a look at the Pomodoro technique for better time management
- The book Project Phoenix gives plenty of tips for designing your own work more effectively
The vision or the goal is often missing in aging software systems. What is the right path? For whom are we doing all this? Does it even make sense anymore?
The product box helps you to find meaningful answers for your software from the customers’ point of view:
- What is actually being developed?
- Who has the benefit?
- What are the central selling points and reasons for use?
- What are the core functions?
- What is the unique selling point of your product (compared to other products or the previous version)?
You will better understand what you are creating software for by answering these questions.
More information
- Design the Box method from gamestorming.com
Over the years, standards emerged from software systems and software development practices. Some of them have been proven to positively influence the development and evolution of a software system regardless the context.
Check within your team which of these standards you are implementing. Where are the potential needs for improvement? In addition, think about why you have not yet addressed missing or insufficient measures.
More information
- The book Accelerate provides scientific evidence good practices for software development
The system is too complex to put on a piece of paper!
– this or something along those lines has certainly been a phrase you’ve heard before as an excuse to avoid visualizing your software architecture.
However, a well-structured software system can fit on a beer coaster – if you choose the right level of abstraction and scope!
Try to sketch the most important aspects of your software’s structure on this card.
- When do you encounter space limitations? Do you have too much unnecessary information in it?
- Does it get too detailed in some places? Could the system be abstracted in different ways?
- Don’t you even know what you are supposed to draw? Do you know how you can hide complexity with blackboxes and hierarchization?
Discuss your drawing approach as well as the outcome. Think about what measures you can take to communicate the structure of your software system even more clearly.
More information
- The documentation drawer system arc42 defines different views on your software system that might help you to communicate your system’s structure.
- The C4 model provides defined views and abstraction levels for visualizing your software architecture.
You might have already encountered this problem: You think you’re doing everything right, but suddenly, a stakeholder wants something completely different. The lack of understanding is huge and frustration increases.
What do you think drives this person? Try to put yourself in their shoes and think about the underlying motivation behind the stakeholder’s behavior. How can you respond to their needs to make the situation more productive and more agreeable for everyone?
More information
- The Mini Quality Attributes Workshop is essentially about better understanding other stakeholders and their needs
- Article about Empathy Driven Development by Andrea Goulet
Issues cause costs. If those costs of the issue are disproportionately higher than the costs of the solution, it is profitable to address the issues for economic reasons.
This card helps you to record a very important problem in a structured way and lets you estimate the associated pain and costs. The interval for your problem cost estimation allows you to indicate how certain or uncertain you are with your estimation. If the interval is wide, it might be a good reason to take a deeper look into the problem or to divide it up into smaller ones.
More information
- The Architecture Improvement Method aim42 shows further applications of issue cost estimation
Software developers solve hundreds of small and large issues daily. We are therefore conditioned to work out solutions quickly. However, in some challenging situations, this is counterproductive. We often react with our trained solution repertoire to the first apparent problem that seems obvious to us.
This card should help you overcome this initial instinct, whereby you first find out the real problems by asking concious why?
questions.
Try to use the so-called “5 Whys” in tricky situations to solve symptoms continuously and tackle the root causes of the problem at the right time.
More information
- Explanation of the Root Cause Analysis on the Architecture Improvement Method aim42
Often there are self-evident solutions in front of us, which contribute significantly to the success of a software system, but we do not see them yet. We are too much caught with our narrow-mindedness in our daily business.
This card solves this dilemma by deliberately taking you into the distant future. This opens up a completely different perspective on “today then” as you now look back on the present.
Once you have arrived in the future, collect the TOP 3 actions that have happened to make your software system successful. Discuss afterward, again in the here and now, why you haven’t taken the actions yet:
- What needs to happen to make you better off?
- What happened just before?
- What happens up next?
- How can you start now?
More information
- Article about the use of the hypothetical press release at Amazon
- Collection of similar formats, which work with future scenarios
Writing documentation is one of the most unpopular tasks in software development. Very frequently, the importance of documentation is not appreciated or dismissed as cumbersome.
Good documentation not only helps others but also benefits the person writing it. Writing and updating the documentation does not have to be magic. You can do it parallel to development – even within the already running development environment. Using arc42 provides a solid foundation for good and easy documentation of software architectures.
More information
- Official Site of arc42
- Lightweight, developer-friendly documentation with the Docs-As Code Approach
In many cases, one does not think about what led to the often fatal outcome until after the end of a project. In agile projects, retrospectives can help identify risks for a project at an early stage, but these are often limited to the past few weeks’ events.
In both cases, we could happily work our way through until we get a hard cut in the form of a project termination – which we can’t even explain to ourselves at that point.
But why does it have to come to this point? Think about what could cause your product to hit the wall in the near future. Do this for different time horizons to avoid being trapped in the here and now. Then use this knowledge to define and implement suitable countermeasures.
More information
- A similar approach are pre-mortems, which help you to find weak spots in your way of developing a software system
Many teams are not aware of how great their software actually is and where dangers lurk for their success. The analysis of the current situation helps you to find unused opportunities and identify blind spots.
Discuss among yourselves with which strengths your software can score points:
- What has been going really well so far?
- What are you really proud of?
Also, ask yourself what weaknesses are currently present:
- Where are you struggling?
- What are you missing?
On this basis, look for opportunities to compensate for the weaknesses identified:
- What opportunities can you take in the near future?
- What can you change yourself right away?
Identify threats that are hidden in your software:
- What are the unfavorable developments in your environment?
- Where are the possible threats?
More information
The term “technical debt” already seems very jaded, vague and even abstract today. Make it clear what is meant by this term within your team for your software system. In the end, they are liabilities that you need to get rid of if it is worth it. Estimate what kind and how much of “technical debt” you are carrying. Define and discuss the found issues among yourselves so that it becomes clearer what your software system really lacks.
More information
- This article by Martin Fowler makes it clear why this topic needs to be addressed
There are people involved with and around your software who have a huge influence without you knowing it. Find out which persons have an important role in the success of your software product as well as how much and how they perceive your software system. Are they rather winners or beneficiaries? Or do they tend to lose something if your software system is successful? Do they have a hidden agenda and maybe even manipulate your development?
Approach the respective persons according to their views about your software system:
- How can you improve communication to influencers?
- How can you keep assurances?
- Who can be held accountable more effectively?
- Who can support you if you need to escalate something?
More information
- Related method of Stakeholder Analysis
Similar to horror movies, there are also monsters in software development. They don’t cost you your life, but they do cost you a lot of time, nerves and in the worst case even money. God objects upon which a huge application depends, switch statements with countless entries or a parameter list which takes up half of the screen: all these are monsters we may encounter every day. What does your personal code smell monster look like? Draw it on the card! Think about measures on how you can defeat it!
More information
- The book Working Effectively with Legcay Code by Michael Feathers covers some of these topics and shows appropriate refactorings
- Refactoring Guru lists a lot of code smells and measures on how to get rid of them
- In the book Refactoring for Software Design Smells, Girish Suryanarayana, Ganesh Samarthyam and Tushar Sharma provide a taxonomy of code smells as well as many ideas for code improvement.
Often we have several hundred pages of documentation – and nobody seems to understand it. Or the documentation is hopelessly out of date. As a result, little or none documentation is usually created or existing documentation is no longer maintained by the developers. Rarely do we question the reasons for this lack of understanding. With our checklist you can verify in a few minutes whether the existing documentation is properly tailored to the target group and recent.
Please cross the appropriate box for each question that you can answer with a clear “Yes”. Are there certain areas that are not OK? Then you already have the first hints where you can improve your documentation step by step. Ideally, you should do this check regularly so that you can be sure that your documentation is always up to date and targeted towards your goals.
More information
- Gernot Starke about the Principles of technical documentation
Are you stuck with a challenging problem? Do you have to implement something swiftly but don’t get an idea of how to do it? Are you desperate because you lack inspiration?
Ask yourself: What would a person you admire do in your situation?
- What would Margaret Hamilton say about your “challenges” in developing and implementing reliable software?
- How would James Bond eliminate performance bottlenecks in the database?
- What would the Cookie Monster do with your numerous zombie tickets?
Get out of your pitfall by consciously creating a different perspective on your problems!
In a fantasy world, if the conjurer knows the real name of the evil she’s confronting, she can unsummon the demon with a flick of her wand. Wouldn’t it be nice to be able to do the same, only with our software systems?
Unfortunately, we developers are left without such a magical device. Even if we do know the root of evil in our software, there is rarely — or even never — a quick solution at hand. It takes a lot of hard work to improve our software system at least a little bit.
But maybe this image of a conjurer’s wand will help you reflect on your system while you’re waving the card. Think about the fixes your spell could provide. And then discuss the results with your team.
Who knows, maybe you might even come up with a magical idea that could solve a problem or two.
Different software systems with their varying software architectures also require different skills of the parties involved in order to be successful.
- Which skills would be of particular value in your team?
- Do you have the required skills within your team?
- Which skills do you implicitly assume but have not yet communicated?
Find out with this map by writing the four most important skills into the four fields! You want to be more precise? Then assign additional points from 0-100 to determine the level of the particular skill.
If you detect that you lack the necessary skills, look for opportunities to acquire them or bring people into your team who possess these skills.
As developers, we often can’t wait to start a new software project. But too rarely we ask ourselves: “Are the fundamentals for a successful software system known to us?”
If this is not the case, no matter how hard a team tries:
- The motivation will steadily decrease because a common goal is missing in the team.
- Nasty surprises in the guise of risks lurk everywhere because they have not been anticipated.
- You will encounter constant conflicts and tensions because necessary trade-offs have not been assessed and disclosed.
- The goals for the relevant stakeholders will not be achieved, as neither of these are known.
This checklist will help you assess whether you have thought of the most critical matters in the initial phase of your project and give you food for thought about what you might be missing.
More information
- Michael Keeling provides many hints for successful software projects in his book Design It! From Programmer to Software Architect
- The software architecture documentation toolkit arc42 provides space to record the most important things about the architecture of a software system
Investments reveal a lot about the status of a software project. Often you as an architect have to deal with technical matters (important) in contrast to the product matters (urgent).
Support/Bugfixing – errors are often easier to fix the sooner they are identified in the software development cycle. Hotspots for errors are good candidates for refactoring. Ideally, you should get a value below 10% here – very likely, the value will be greater.
Technical improvements – by reducing the technical debts of your system, you improve the quality of the software and at the same time reduce the costs for bug fixing as well as development times of new features.
The recommendation is about 10-15%.
New features – the development of new features brings business value, so you should invest the most here. At least 50% or more of your development time should be spent on this to create new value.
Architectural work – Only through continuous work on the architecture can you keep the software alive and enable addressing new future trends and requirements. The recommendation is about 15-20% in larger projects.
More information
- We are missing a reference here. Feel free to contact us if you come across it!
- aim42 - Architecture Improvement Method gives you plenty of ideas on how you can make investments the right way.
Many people associate architecture documentation with long and complex documents — mostly of questionable validity. The barriers are correspondingly high, even to start with a documentation. But this can be quite simple, as demonstrated by our Minidocu.
Start by stating the business reason for the software or briefly describe it. So it is clarified why you need this software at the first place. Then note the three most important quality attributes, sorted according to their priority. Finally, list the most important design decisions so that they are sustainably documented and verifiable.
With this minimalistic version of a documentation, you can lay the foundation for a more comprehensive architectural documentation. To create this without unnecessary overhead, a template such as arc42 can be used.
More information
- The architecture documentation toolkit arc42 and especially the FAQ section give you pointers to a minimalistic documentation.
- Lightweight, developer-friendly documentation approach Docs as Code shows you how you can make documentation a first-class citizen.
Every day, decisions are taken that often have a long-term impact on our software system. Each of these decisions is based on several alternatives, of which, however, only one can ever be selected as a solution approach. The selected solution is usually described in an architecture documentation and is therefore comprehensible. But what about the alternatives, which have also been considered but were not chosen? These should also be documented so that the decisions made can be understood in the long term.
Now, think about which paths you deliberately did not follow in your software. Write them down on the card and describe the reasons for the rejection of the individual alternative.
More information
- Michel Keeling lists “Paths not taken” as one of dozens of activities in his marvelous book Design It!
- Introductory page for the topic ADR
- Initial presentation of the idea of ADRs
None of us can do everything, but surely each of us can do something especially well. Sharing this special knowledge helps you to make your team even better and reduce knowledge islands.
So, what is your special subject of expertise? Write the topic down on a card and think about which five guides, books, blogs, or other resources you would recommend to others to get started. Sort them, starting with the most basic resource, and write them on the card as well.
Afterwards you can discuss your results. Maybe someone else choose the same topic as well and nobody was aware of it? Awesome! You’re the only expert in a subject? Why don’t you give a talk about it?
If you do this with your team, this will result in a greater distribution of knowledge. Ideally, collect the filled cards in a location that is accessible to everyone in the team. This allows everyone to access the learning resources and expand their knowledge at any time.
- Markus Harrer lists some of his personal TOP 5’s on his blog.
Although we hate to hear it: risks are part of our projects from the very first moment. Often, however, both these risks and their countermeasures are forgotten to be documented accordingly. This can later have fatal consequences if, for example, you have relied on too fragile adjacent systems, or perhaps also ignored relevant regulatory issues.
Think about the risks in your project and document one risk per card. Afterwards, write down the measures you have taken to minimize the risk and the expected impact.
Discuss the results with each other. Perhaps you have discovered a previously unknown risk? Very good! Now you can make your project a bit safer and extend the architecture documentation. In addition, you can raise the awareness of both yourself and affected stakeholders.
Everybody has experienced it: You are allowed to start a new project and are spoiled of choices when it comes to the selection of technologies to be used. As a engineer, of course, one prefers to take the latest programming language or the latest and hottest framework, but is it economically even justifiable? Often there is hardly any support for new technology, few specialists exists and ocassionally the wheel also has to be reinvented. All this costs money – in the worst case, a lot of money. In order for you to understand the economic factor of a technology decision, this card will help you to answer the most important questions.
To do this, compare two technologies that you would choose for your project. Then decide for each question which of the two meets the requirements better.You can use a rating system that suits you, for example, a scale from 1-5. At the end, sum up the individual score per technology and compare the results. You may be surprised that perhaps it is not the new super technology that has “won” but something older and more established.
You can now use the result of this evaluation for further project planning and architectural documentation. The evaluation also helps you to be able to support your decision to the project manager, who pays less attention to technology but all the more to the economic efficiency of a solution.
More information
- The “Boring Software” manifesto give you ideas at what you’ll also need to look at when you want to choose a technology
Do you recognize this? Developers just returned from a conference and would like to put all the new stuff they’ve just heard of into the software system right now? The temptation might be great, but “conference-driven development” isn’t the best approach and all the existing stuff constrains your freedom of choice, too.
How can you communicate that you address the developers’ ideas about renewing your tech stack and keep the balance with the stuff that’s already existing? This card allows you to set a roadmap for the technologies you use or want to use in your software system. Put your new and existing technologies in different stages of adoption:
- Hold on: Already heard; doesn’t really fit to us yet
- Assess: Could be interesting; we’ll find out more about this
- Trial: There’s a good use case that we’re implementing in our context
- Apply: Yes, it’s worked out well; we’re adding it to our standard portfolio
- Stop: Okay, we’re not gonna use it in new projects anymore
- Remove: Everywhere where we come across it, we remove it
By doing this, you achieve two goals: Developers with the urge to introduce new technologies feel heard because they see that you have addressed their ideas by putting them on the roadmap. On the other end, developers see which technologies they don’t need to invest time to learn certain technologies that’ll get removed soon.
PS: This roadmap is not limited to technology only. You can also communicate practices and methodologies you want to apply or get rid of.
More information
- A similar procedure can be found in the Technology Radar (which we used as inspiration). We added the stages “stop” and “remove” because we thought you could not just put stuff into software systems, but you also have to get rid of them.
“Let’s add this new framework that was launched last week!”
I’m sure in one of your projects you have heard this statement in a similar form before or even made it yourself. First and foremost, you develop your software for your users. And yet, far too little attention is paid to this when making decisions, what benefits your target group has from the upcoming change.
You want to write your own complex logging framework for your software and estimates a development time of about six weeks?This will most likely have no noticeable impact on stakeholders, but simultaneously prevents you from developing new features during this time.
You plan to integrate another new payment method into your system, but aren’t you sure if nine weeks of development time can be spent on this? Many of your users might be grateful to have a new opportunity. This will most likely have no noticeable impact on stakeholders, but simultaneously prevents you from developing new features during this time.
You plan to integrate another new payment method into your system, but aren’t you sure if nine weeks of development time can be spent on this? Many of your users might be grateful to have a new option to pay for products. So this feature has a very big benefit.
With this card you, can check your next decisions regarding how much benefit users get from the changes and whether your discussions actually are useful.
More information
News
31/05/2022: Released printed English edition and improved website
19/04/2022: Merged English version with the German one
07/08/2020: Added support for short URLs.
31/07/2020: Added translation for cards.
30/07/2020: We’ve published the repository with the English version. It’s still work in progress, but we are moving forward!
more news are listed on the German version
Frequently Asked Questions
How do I get the printed cards?
The printed card packs are available at conferences where INNOQ participates (e.g., DeveloperWeek, Goto conference, or JAX). Markus also offers shipping cards from time to time (at least in his training courses).
Do you have a file with all cards?
Yes, we have. You can download a PDF file with all cards at once: cards42 English edition.pdf
How was the idea born?
Once upon a time, Markus Harrer (the initiator and main contributor) went after an internal INNOQ company event to a bookstore and discovered “50 Karten: Kunterbunte Mitmach-Karten für das Handgepäck” (rough translation: “50 cards: colorful activity cards for your hand luggage”). These cards were designed to encourage children to think about various things. Markus was heavily inspired by these cards and created the initial idea for “Activity Cards for Software Architects.” The cards42 project was born.
Why the name “cards42”?
With this name, we follow the tradition of Gernot Starke (INNOQ Fellow) in the naming process. Gernot has already created the projects arc42 and aim42. He also explained the origin of the number 42.
OK, and of course, the domain was still available ;-)
Why is there a logo with “INNOQ” on the cards?
INNOQ is the company where the main contributors are employed. The company gives the main contributors the time for creating and maintaining the cards42 project. INNOQ also prints the cards on paper and spreads these cards packs on various occasions.
Feedback
You are welcome to send us feedback on cards42. Please use GitHub Issues or write to us on Twitter. For longer feedback, you can also contact the initiator of the project, Markus Harrer, directly via e-mail at markus<dot>harrer<at>innoq<dot>com.
Contributors
- Markus Harrer (Translation, initial idea and prototypical card design)
- martina (many translations, examples for cards)
Contributors to the original, German version:
- Sonja Scheungrab (Re-design and printing)
- Tobias Erdle (CSS optimizations and texts)
- Lisa Maria Moritz (Texts)
- Ben Wolf (Card ideas, reviews)
- Simon Harrer (Card ideas)
License
This work is licensed under Creative Commons - Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).