Architecture Communication Canvas

Development teams usually don't like to write documentation. By way of contrast, a certain amount of documentation often proves useful in the long run. Why not give the established Canvas pattern a chance to shine in software architecture?

In this talk, you will learn a highly pragmatic approach to document and communicate the most important aspects of your architecture (and implementation). It is compatible with the established arc42 template but significantly shorter.

Prepare yourself for an example-ridden talk and plenty of practical tips that will make documentation fun and productive!

Transcript

1. Architecture Communication Canvas C o d e t a l k s / R e g e n s b u r g / 7. N o v e m b e r 2 0 2 3 Low(est) effort architecture documentation BENJAMIN WOLF @BEN@INNOQ.SOCIAL Photo by Raychan on Unsplash
2. „You can solve any problem with good coffee.“ Benjamin Wolf Senior Consultant / Coffee Consultant at INNOQ Consultant for architecture development / documentation Trainer for iSAQB Foundation, IMPROVE and ADOC arc42 practitioner and maintainer Coffee connoisseur
3. Why this topic?
4. The Endless Void ... Photo by Rubén Bagüés on Unsplash
5. Nobody Finds a Thing image by DALL.E
6. Documentation as Denial-of-Service Attack https://wiki.eclipse.org/EclipseLink/Development/Architecture/EclipseLink/ClassDiagram
7. You • need* to document • have limited time * if we were younger and naive, we would have written „want“ Assumption
8. Agenda What is a Canvas? arc42 in a nutshell ACC architecture communication canvas
9. Agenda What is a Canvas? arc42 in a nutshell ACC architecture communication canvas
10. Abstraction is your best friend! very sparse less sparse!
11. sparse Element Description PayProv All our payment providers A-D less sparse! Courage to leave things out* (1)
12. sparse Courage to leave things out* (2)
13. Use the Canvas what? Photo by Kari Shea on Unsplash
14. Can-what? wtf? Photo by Kari Shea on Unsplash
15. explained by chatGPT ERD Block Petri In software engineering, a canvas typically refers to a visual container where users can interact and manipulate elements to create or modify content. *!$§* NO https://chat.openai.com/share/ce9455a9-4d17-4e32-a590-a53136ea481a Canvas (1)
16. explained by us ERD Block Petri ... A canvas is a structured visualization that facilitates understanding and analysis of key elements of speci f ic topics.. YES! Canvas (2)
17. ERD Block Petri whow! Business Model Canvas https://www.strategyzer.com/books
18. Business Model Canvas ERD Block Petri https://www.projectwizards.net/en/blog/2019/09/business-model-canvas
19. ERD Block Petri Business Model Canvas
20. ERD Block Petri Bounded Context Canvas
21. many more … https://canvanizer.com
22. https://www.workingsoftware.dev/software-architecture-canvas/ Thanks, Patrick!
23. for new systems Thanks, Patrick! https://www.workingsoftware.dev/software-architecture-canvas/
24. Agenda What is a Canvas? arc42 in a nutshell ACC architecture communication canvas
25. 25 1. Introduction and Goals 2. Constraints 3. System Scope and Context 4. Solution Strategy 5. Building Block View 6. Runtime View 7. Deployment View 8. Crosscutting Concepts 9. Architecture Decisions 10. Quality Requirements 11. Risks & Technical Debt 12. Glossary 1. Introduction and Goals 1.1 Requirements Overview 1.2 Quality Goals 3. System Scope and Context -> external interfaces 4. Solution Strategy 5. Building Block View 5.1. Whitebox Overall System (Level 1) 8. Crosscutting Concepts 9. Architecture Decisions Main requirements, especially quality goals Neighbouring systems and external interfaces Core idea of the solution, suggestion: bullet points only Top-level structure of the code Cross-cutting concepts, highly detailed Important archictecture decisions, incl. decision makers and date arc42 in a nutshell
26. Agenda What is a Canvas? arc42 in a nutshell ACC architecture communication canvas
27. Structure of the Canvas
28. ERD Block Petri • Business-Case-in-half-a-Tweet • The 3 most important capabilities • The 3 most important quality attributes • Key Stakeholders • Most important neighbouring systems • Most important components • Most important technologies • Proud factors and worst decisions • Risks and issues Original Key Questions
29. ERD Block Petri • Business-Case-in-half-a-Tweet • The 3 most important capabilities • The 3 most important quality attributes • Key Stakeholders • Most important neighbouring systems • Most important components • Most important technologies • Proud factors and worst decisions • Risks and issues Original Key Questions
30. ERD Block Petri https://canvas.arc42.org
31. • Create canvas prior to review • Common understanding • Remind participants of „everything“ Use for Reviews
32. • Fastest possible start • Avoid blank-paper syndrome Use to Kickstart https://unsplash.com/de/fotos/-4trKf0Kbow
33. • Fastest possible docu • If nothing else works... Use in an Emergency
34. Examples What is a Canvas? arc42 in a nutshell ACC architecture communication canvas
35. Health-Insurance Card ERD Block Petri
36. Salary Management Block
37. Open-Source HTML Sanity Checker
38. ERD Block Petri • Valuable documentation in less than 2 hours! • Aha moments! Lost treasures! Fun!! • Getting started with documentation! Real Talk
39. Block
40. More Info on ACC
41. Block Architecture Inception Canvas Architecture Communication Canvas Tech Stack Canvas techstackcanvas.io canvas.arc42.org workingsoftware.dev arc42 The Big Picture
42. Architecture Inception
43. Tech Stack Canvas
44. www.innoq.com Benjamin Wolf benjamin.wolf@innoq.com LinkedIn: benjaminwolf1985 Mastodon: @ben@innoq.social