- Babelfish for Software Architects – Communication with Stakeholders
In practical work, software architects must collaborate with people in many different positions and roles. The…
- Babelfish for Software Architects – Communication with Stakeholders
In practical work, software architects must collaborate with people in many different positions and roles. They largely operate without authority, meaning they must rely more on communication and motivation than on the authority of a leadership position. Figure 1 shows a selection of the most important communication partners.
Prof. Dr. Michael Stal has been working at Siemens Technology since 1991. His research focuses on software architectures for large complex systems (distributed systems, cloud computing, IIoT), embedded systems, and artificial intelligence. He advises business units on software architecture issues and is responsible for the architectural training of senior software architects at Siemens.
Software architects communicate with a wide variety of roles and people in their work (Fig. 1).
Naturally, software architects should be careful not to suffer death by meetings. These should be limited to the necessary minimum, as overcommunication is just as counterproductive as under-communication. The Waterfall model often tends towards undercommunication initially but towards overcommunication in later phases, sometimes called panic mode. In agile environments, communication efforts are ideally distributed evenly over the project duration.
Architecture as a Means of Communication
Software architecture serves as a mandatory guideline for implementing the problem, i.e., the requirements. Therefore, its communication is essential not only for developers. The following means are recommended for communication:
The architecture documentation must cover not only the what and how but also the why of the architectural decisions made. Some architecture documents show that architects have unmotivatedly fulfilled their documentation duty, which makes things difficult for the target groups and ultimately for the architects themselves. Therefore, they should carefully consider beforehand what information stakeholders such as product managers, testers, or developers need.
To structure and complete these documents, it is advisable to use an existing template like arc42. Figure 2 shows the arc42 guidelines with Level 1 (white-box description of the entire system and black-box descriptions of the components within it) and Level 2 (zooming into some components of Level 1). Level 3 would zoom into Level 2, and so on.
The arc42 documentation template contains guidelines for suitable and well-structured architecture documentation (Fig. 2).
(Image: arc42)
Such templates are based on decades of experience and typically follow a top-down approach to avoid overwhelming readers. Of course, the documents should not be too extensive but should refer to corresponding documents for subsystems or components for detailed information. A maximum of 60 to 80 pages per document has proven effective in practice.
Successful communication should not be limited to exchanging documents but should also take place via presentations and workshops as multi-channel communication. It has proven beneficial to show a presentation with the most important core elements before handing over the architecture document. Some companies even organize workshops with users and customers for this purpose.
To convince communication partners, architects must be able to justify their decisions. Architecture Decision Records (see Figure 3) help with this. They specify the topic of the decision, show possible alternatives, and explain why one alternative was preferred. They are stored along with the codebase in source management systems like GitHub. This benefits not only newbies but all stakeholders who want to be informed about decisions.
Architecture Decision Records help document architectural decisions (Fig. 3).
From software patterns (see Figure 4), an idiomatic language emerges for more effective communication, benefiting all parties involved. Instead of talking about an event source, an event interface, and event consumers, for example, simply mentioning the Observer pattern is sufficient. This eliminates the need to explain individual classes and interfaces, utilizing a higher level of abstraction. This also applies to DDD patterns (domain-driven design) at the business domain level.
Patterns like the Activator can significantly simplify communication between software developers because they build on a higher level of abstraction than program structures (Fig. 4).
Using simple tools like whiteboards, blackboards, or flip charts in a low-tech-first approach has many advantages. They allow for freer and more interactive communication and collaboration and help in using an adequate tool for every purpose. Frequent media changes also increase attention. A relatively simple method involves index cards divided into three sections. In the top, slim horizontal segment, a class or component name is written (see Figure 5); below it, on the left side, is a "Responsibilities" column with the component’s responsibilities, and to the right is the "Collaborators" column, listing other components with which the current one collaborates.
With CRC cards, architectural designs can be easily discussed on a whiteboard (Fig. 5).
These CRC cards (Class-Responsibilities-Collaborators) are easy to create, attach to a whiteboard, group, or connect with threads. This way, design discussions gain an adequate tool for communication. UML tools then document the results of such discussions in an electronic format.
It has proven beneficial for software architects and developers to create a ubiquitous language with domain experts, following the domain-driven design (DDD) approach, which defines business concepts and their relationships. This helps avoid misunderstandings later. The development and improvement of this language are continuous. Additionally, DDD offers an approach driven by the problem domain, preventing developers from rushing too quickly into the solution domain. Thus, in DDD, software architects focus on developing a suitable language for the business domain and, at the beginning, deal exclusively with the issue space or the business domain.
If architects merely hand over documentation to others and then disengage, architecture drift almost always occurs. This means the implementation does not match the design. The reasons for this can be manifold: developers may have been under time pressure, did not understand the architecture, or replaced what they considered nonsensical decisions with their alternatives.
Therefore, it is advisable to practice management by walking around, meaning continuously mingling with developers, gathering their feedback, and clarifying questions. Architects should also participate in implementation, not just to follow the "eat your dog food!" rule but to stay in contact with developers. However, it would be counterproductive for architects to work in the critical path.
Reviews, in addition to optimization aspects, also have communication aspects. An architecture review can typically clarify questions as well as identify problems and risks. Furthermore, it increases the understanding of issues and the architecture among all participants. Many projects underestimate this aspect. Reviews should take place with every increment or sprint to resolve issues early. This naturally also applies to code or design reviews.
As a lightweight method, architecture design reviews are suitable for obtaining short-term feedback from customers or users. For this, the architect compiles documents or development artifacts and a questionnaire with tasks. For example, the development team has created a cloud-based persistence solution with AWS S3 and needs feedback on usability. The architect provides the implementation along with documentation or a URL through which reviewers can use the service. Additionally, they add a questionnaire for the reviewers that asks, among other things: "How long did it take you to create a directory and store a new object there via the API?" or "Is the documentation adequate from your perspective? If not, please provide suggestions for improvement." The effort for such reviews is manageable, yet the benefit is significant. It is advisable to allocate one day for the author of the review and one additional day for each reviewer.
Knowledge Replicas: In some projects, pitfalls arise because certain expertise is concentrated in only a few individuals. If a person leaves the company, problems emerge. Therefore, an information-sharing culture is recommended, to which software architects can contribute. Several people should possess every critical piece of knowledge. Information can be shared through coaching or mentoring. This is especially true for knowledge brought in by external consultants. Such desires are sometimes met with resistance from knowledge holders who want to secure their knowledge advantage and their importance to the company, which is why corresponding incentives are needed, such as additional monetary compensation or visible appreciation.
Metrics and Quality Assurance through architecture evaluation tools (see Figure 6) enable the assessment of architecture quality, for example, regarding dependency cycles, codebase size, hot spots for errors, or complexity aspects. What might initially seem like a purely technical facet also proves useful for communication, as pure gut feeling is often unconvincing. With concrete numbers, other stakeholders are more likely to be motivated to implement and finance improvement measures.
Architecture tools like Structure 101 enable quality analysis of one’s own software architecture and codebase (Fig. 6).
Early clarification of open questions plays an important role at the project start. Software architects should proactively approach other stakeholders to clarify business aspects, requirements, or the test strategy. This applies even if other roles are responsible for this activity. For example, the requirements catalog is often in need of improvement due to missing important information or clear priorities, especially concerning quality attributes. In the latter case, software architects create a utility tree with self-estimated priorities. They then discuss this with the responsible roles, thus taking the initiative.
In projects, software architects and developers often face a nebulous and dynamic environment. The requirements catalog is not finalized or is of poor quality. There is a lack of experience with new technologies, the team has insufficient knowledge or resources, and much more. Two factors help in such situations. Firstly, an agile process with sequential sprints and thus rapid feedback offers advantages. Secondly, architects must actively clarify matters with appropriate courage (see previous aspect). If the requirements are incomplete, software architects ideally ensure that at least the most important 20 to 30 percent of the requirements are available promptly. This allows them to ensure a sufficient architecture baseline.
In parallel with the clarification phase, technical prototypes can be created to explore the usability and properties of new or previously unused technologies, and the necessary training measures can be organized and conducted. This approach is derived from the so-called Twin-Peaks model. Convincing other stakeholders is also necessary for this.
Blind Spots: Anyone who has ever created a document or program and, despite repeated checks, simply could not find an error within it knows that the brain can unconsciously suppress details or complete them with incorrect contexts. A famous example is the supposed face on the moon’s surface. Other employees can provide good support here, which is why pair programming or pair designing is helpful.
Retrospectives refer to the often underestimated activity of looking back at the past to learn from it for the future. The driving questions are "What were the causes of failures or problems?" and "What were the key success factors?" In addition to technical aspects, communicative deficits that have caused trouble often emerge. Those in the role of software architect who retrospectively analyze the past should ask themselves where they could have acted better.
Important Communication Questions
Naturally, this article cannot cover all eventualities, but before any type of communication, software architects can ask themselves the following questions, for example:
- Why/what for is this important?
- For whom is this important?
- What do I want to achieve?
- How do I want to achieve it?
- What do the communication partners expect or need (listener context)?
- What personality types are present?
- What is the necessary and sufficient minimum of communication, or how can communication overflow be avoided?
- What attention spans do my conversation partners have?
In addition, there is a crucial and often underestimated factor that always plays a role in communication behavior: How do I manage to make a good impression?
Don’t miss any news – follow us on Facebook, LinkedIn or Mastodon.
This article was originally published in German. It was translated with technical assistance and editorially reviewed before publication.