After we covered what are the common issues of Software Architecture and why having a basic process will help you achieve your goal, let’s have a look at the process elements, the process steps and the description of its different parts. Practicing with these elements will help you become a better meeting organizer and document writer, which is essential for this process to work fine.
This page is part of the guide The Practical Software Architecture:
- Software Architecture Issues and Solutions
- The Process Overview
- Documenting Software Architecture
- Vision, Principles, and Constraints
- Preparing the Roadmap
- Decision Making
The complete process
This is the image summarizing the complete Practical Architecture Process. You can download it and print it for reference. In the following sections, you will see in detail what these flows look like.
Meta: Meetings, Inputs, and Outputs
You need to familiarize with the process elements. As you can see in the complete process image above, they are mainly three:
- Meetings. For the sake of an efficient process, you need to be strict with timing and take quick notes of everything. Nobody likes to spend their time in useless meetings. Try to stop discussions are not leading anywhere or that only involve few persons in the group. Aim to achieve your goals during the session but, if you can't make it, limit it to the time planned and arrange with the rest another date and time to continue the meeting. Ask for feedback and think about how you can improve next time. In this process, every meeting must have Inputs and Outputs.
- Inputs. Never plan a meeting without an agenda: that's the most important input. Also, if the meeting is about making a decision or discussing alternatives, you must send context information in advance and encourage others to read it before the meeting. The better you become in preparing your Inputs, the better the process goes.
- Outputs. Why did you spend one hour in that room? It's a simple question but we tend to forget to take notes during the meeting and write them down afterward. If you follow this process, you may want to register a new entry in the Architecture Journal with the outcome of the meeting, and also update the Architecture Guide if needed.
You don’t need too much text for Inputs or Outputs, put the effort in summarizing as best as you can. In the meeting paragraphs for each flow in this guide, I’ll indicate what to include in those sections.
Meta: Architecture Journal and Decision Log
Decision Log and ADR (Architecture Decision Records)
One of the sections proposed in the Architecture Guide schema is the Decision Log. If it’s the first time you read about it, it may sound like too much work, trivial and unnecessary. However, based on my experience, it’s one of the most useful parts of your work as a Software Architect. The idea, summarized, is that you write down all the decisions that have been made after some time of analysis of the different alternatives. You shouldn’t include too much content, just try to cover these questions:
- Who participated in the decision?
- What is the problem or requirement that you wanted to solve?
- Are there other alternatives?
- What were the Constraints? Why did you choose one instead of the others? (see the section about Decision Making: you may not choose the best one consciously)
- How is that decision going to help solve the problem or requirement?
You can keep your Architecture (or Technical) Decision Records in a version control system like Git. There is even a command-line tool to maintain these records (adr-tools). If you use it, I recommend adding the section “Participants” to make these records more complete.
The reasons to keep a Decision Log are many, and the most useful one in my experience is that the log will save you a lot of recurrent conversations. We tend to forget the context around the decisions we made and, without it, people may start questioning many decisions. That may end up with Architects having to explain multiple times why the system is like it is, which may be frustrating. To better understand the decisions, you need their context.
Not only decisions
I propose to create even a broader scope Journal, which includes not only the Decision Log (whose entries can be either in a different section or you can prefix with [Decision] for instance) but also all the outputs from meetings and discussions that you consider valuable to be shared with others:
- Drawings or pictures from Design sessions.
- Lists of Action Points agreed during meetings.
- Analysis of new solutions or ways of doing things (too early stage to end up in a decision).
- Knowledge transfer session outputs.
For some of these entries, you may also want to create a new section in the Guide eventually. In any case, you’ll have the meeting notes organized, and others can follow what’s going on with Software Architecture.
Anyway, remember to keep these entries as short and simple as possible.
This process defines two different types of Audiences for the meetings: Business Audience and Technical Audience.
The most important advice about meeting audiences is that, for the sake of a fluent process, you shouldn’t include too many people in meetings.
On the Business side, try to find people who are willing to participate in the process and that have good knowledge about the project. At the same time, it’s important that they have decision power, so the outcome of the different meetings don’t need to be reviewed or supervised by someone else afterward. Three or four people maximum is a good number for this audience.
The Technical Audience is usually more difficult to define. Usually, many people want to participate and express their opinion on the important decisions of Architecture. However, you should keep the Audience of the technical meetings to no more than five people, since everybody in the room needs to participate and discuss. There are different ways to achieve this:
- Create communities around different topics: Data, Code Conventions, Testing, Infrastructure, APIs, etc. Then, ask for volunteers to attend to these different communities, taking into account that they should be no bigger than 4 or 5 members. This split becomes tricky sometimes during the process since, depending on the topic that you're going to cover, it might be that sometimes you need to ask for two or three different communities to discuss a topic, so they need themselves to pick who is going to attend so the audience is always restricted to a smaller group.
- Ask for fixed delegates that can either make turns every few weeks or stay for a longer time. In any case, it's important that teams feel represented by these persons and they become somehow ambassadors of the architecture, communicating decisions and collecting inputs from the rest of the team.
The most important idea here is to keep small and representative audiences.
Now, continue to Documenting Software Architecture to learn how you can organize your docs without creating a big mess.