Dieser Blogpost ist auch auf Deutsch verfügbar
The approach of visualizing essential information on a specific topic in a highly structured way on a single sheet of paper has been made popular by Alex Osterwalder and Yves Pigneur with their “Business Model Canvas” (BMC). The BMC book has sold millions of copies and is considered a classic for modern companies and startups. We see one reason for this success in the reduction to an absolute minimum of information: The BMC simply leaves no room for detailed or sprawling documentation. You need to focus on the essentials.
Since the BMC in 2010, a number of other canvas models have been added, such as the “Lean UX Canvas”, the “Product Design Canvas”, or the “Bounded Context Canvas”, which is helpful for fans of Domain-driven Design (see below).
What is a Canvas?
We asked ChatGPG, and got the following answer:
In software engineering, a “canvas” typically refers to a visual container or surface where users can interact and manipulate elements or components to create or modify content..
This explanation is correct, but it rather refers to UI frameworks (like Tkinter, wxPython, HTML5, Java2D, JavaFX or WPF) that use a canvas as drawing surface.
In our context, the word canvas has a slightly different meaning:
A canvas is a structured visualization that facilitates understanding and analysis of key elements of certain topics.
All clear, right? As we love brevity, here’s the definition in simplified form:
Canvas: ordered representation of key elements.
In other words, it is about essential information (aka “key elements”) on a topic. This might concern a business model, as in the Business Model Canvas, or important information about a software architecture.
The concentration on essential elements is commonly known as abstraction or modelling – that is, the omission of unessential details. Such models serve a specific purpose, and which elements a model emphasizes in each case depends exactly on that purpose.
Structured Summary
The idea of structured summaries is used in both education and business. We use a structured summary to collect essential facts on a topic. The following figure shows an example for Maine-Coon cats.
But let’s get back to software and IT. You can use structured summaries (aka canvas) for technical documentation.
Isn’t that what arc42 is for?!
But of course! You can use the arc42 template and fill it very sparingly. However, in reality arc42 is mainly used as a document or wiki, which is way too cumbersome or too much effort for some teams and people.
We were often asked for “even shorter documentation” in projects, and worked together with various teams from different industries to refine their documentation and make it even more compact. But for a long time, we still recorded the results in the (classic) template. That works well in itself – but it is still not as compact as a canvas.
What those disciplines can do, we can also do in software architecture: present the essential highlights of a system in a structured way in a super-compact form – with the Architecture Communication Canvas.
As you’re used to from the arc42 template, this canvas is also available under a permissive open source license, so that you can use it in commercial and professional environments. The canvas itself, its documentation, and the related website https://canvas.arc42.org are maintained in a public GitHub repository.
Key elements of IT systems
To truly understand the essential inner details of IT systems, we need answers to three key questions:
- What is the purpose of the system? In other words: What are the requirements?
- What does the solution look like? In other words: What are the essential aspects of the architecture?
- What are the (known) problems?
If we refine these three questions a little more, we arrive at the following list of key elements that we need to know about:
- What is the business case of this system? Why does it exist?
- What are the main capabilities or functions of this system?
- What are the crucial quality requirements concerning the system, like scalability, security, reliablity, and usability?
- Who are the most important stakeholders?
- What is the context of our system?
- What are the most important or most incisive decisions that were made – both good and bad?
- What are the essential components (building blocks, modules) of the system?
- What technologies are used?
- What are material risks and problems?
All this information is also part of the well-known arc42 template, but sometimes it just has to be brief. That’s where the canvas comes in.
A Place for Requirements and Solutions
The canvas provides space for the answers to the three key questions above (requirements here with green background, solution with blue background, problems with red background).
The Business Context is the transition from requirements to solution, therefore this part runs from green to blue.
Examples Instead of Details
At this point we would like to introduce the canvas only briefly, without going into the detailed meaning of the individual elements. If required, you can read about them in the online documentation. Below you will find the canvas as a diagram and also a few download links to get you started right away.
In any case, we would like to show you two examples so that you can experience the Architecture Communication Canvas in “finished” form.
Mass Market CRM (MaMa CRM)
The following example show the canvas for the software system MaMa CRM. Gernot Starke gave advice to the development teams and documented the system extensively and with the arc42 template. You can read the detailed documentation in arc42 by Example.
Salary Software (gehalt.io)
This example showcases the canvas for the software system “gehalt.io”, an INNOQ-internal software that was developed by Benjamin Wolf and a few colleagues.
Field Reports and Areas of Application - or: What’s the Point?
You may wonder what you can use a canvas for in the first place, i.e. what could be reasonable application areas. We already used the canvas in various projects for the following:
- As a nucleus or starting point for further documentation, especially in cases where existing systems lacked any systematic documentation. The Canvas helped to avoid blank paper syndrome, and to give the development team a quick sense of achievement.
- As an emergency solution, when the team really (!!) had no time to create further or detailed documentation. When there was really no other way out.
- As a starting point for reviews or inventories: Gernot has written about it here and there. A canvas is a great start for this, providing a common communication base for all stakeholders.
- As an introduction to the topic of architectural documentation, if participants had little or no knowledge in this area.
Regardless of the use cases, our experience has always been as follows:
- We created a piece of documentation that delivers real value in at most one hour.
- Collectively (one of us + 1-n people from the project) answering each area on the canvas leads to “aha” moments, unearths forgotten information, and shows that creating documentation can be fun.
- Documenting a system with the Canvas is an excellent introduction to software architecture documentation if you have little or no experience with it. A positive first point of contact with the topic of architecture documentation should not be underestimated.
Still at the Beginning?
If you have only made a few architecture decisions so far, i.e. you are still in the discovery or planning phase for a system, the Architecture Inception Canvas – also available at https://canvas.arc42.org – can help you. It focuses on new IT systems, and essentially contains requirements, plus a few ideas of the architectural solution.
More Technologies?
If you want to learn more about the technology used in or the technology portfolio of your system, we recommend the TechStack Canvas. Be sure to check it out – it’s a great complement to the Architecture Communication Canvas shown here.
Now what? How do I create a canvas?
We have found it great teamwork to create the canvas for a system together in a group of motivated and knowledgeable people. This works very low tech, with a flip chart, some pens and sticky notes: Hang a blank flipchart sheet on the wall, landscape orientation, with the pure white side up. Roughly transfer the individual segments of the canvas onto this sheet and label them accordingly. You’re ready to go: Start with the top left, with the business goals of the system. Fill in the other segments in any order.
If you prefer to work electronically or online, the canvas is available in the following formats:
- for Miro® (miro template, rtb-Format)
- for draw.io/diagrams.net
- as PDF
Conclusion
What are you waiting for? Quickly grab your pen (or drawing tool), and bring a few keywords to your system to the canvas. A sense of achievement is (almost) guaranteed. If you want to make your canvas available to the public – create a pull request in the canvas repository.
Acknowledgements
Thanks to Patrick Roos for his idea and work on the architecture inception canvas, Jörg Müller, Peter Hruschka and some of our clients for feedback to the canvas. And to Lucky, the best Maine-Coon cat!
And one more thing: In case you like to enjoy the canvas in INNOQ-typical colours – here you go (click the image for a high-res version):
