Intro: what is a Software Architecture Process?
Table of Contents
Keeping an efficient Software Architecture can save you a lot of time, and also help build the foundations of a successful Software Project. But, how to set up a way of working that is at the same time efficient, easy to implement and compatible with Agile methodologies? That’s what I’ll cover in this guide.
The definition of a process is:
A systematic series of actions directed to some end.
How does that apply to Software Architecture? First, Let’s try to define what is our end.
In most organizations, the goals of having Software Architects are all (or a subset) of these:
- Get a Software that is flexible, scalable, modular, fast, etc. The specific list of System Quality Attributes for your project may of course vary.
- Build a Vision, that shows the long-term technical shape of the project.
- Provide experience in applying patterns and techniques to solve problems.
- Coaching others, so the knowledge is spread among the team members.
- Create, and especially help others create, new ideas that may provide a competitive differentiation to the project.
The better an Architect is in doing those tasks, the better the produced Software Architecture of the project is. Therefore, the goal is to perform those tasks as good as we can.
And how to get there? Sometimes we just improvise and react to what’s happening at the current time. But, can we come up with a systematic series of actions so we can focus on the creative part of it and forget about all the boilerplate tasks? That’s what I’m calling here the Process, and I’ll help you set up your own one based on this reference, The Practical Software Architecture Process.
Why do you need a Software Process?
Your way of working does not work
If you’re looking for new ways of doing Software Architecture, it is because probably you come from one of these situations, each with its own problems:
- No process at all. Which means that there is scarce documentation (or maybe none) about how your software is structured, how it behaves and where you want to go with it. Another potential symptom of not counting with a good process is having a Meeting-Only Software Architect, that only participates in the software creation process with design meetings, which outcome doesn’t include an action plan and which contents are normally forgotten in a week. Even though the Software Architects may have a perfect picture of the entire architecture landscape in their minds, for the developers there is a feeling of chaos and the odds are that you deviate from the decisions and conventions very often.
- Fake “Agile” Architecture Process. This is a broad concept, but here I use it to define the situation of not having any process at all and pretending that it’s the best way to go since your company is Agile. In this scenario, you often hear things like “the code is our documentation” and “we don’t do diagrams since they become obsolete very soon”. Same as the first case, this strategy might work for small teams when combined with a very good communication between its members but, as the team grows, discrepancies and the fact that there are no rules nor conventions may introduce a lot of noise in the daily work.
- Heavy (and boring) process. On the other side, there are also situations in which the architects are trapped inside an endless Architecture Process in which everything the team does has to be paired to a formal document, no matter if it’s UML, Word or even a proprietary platform. The problem here is twofold:
- The documentation produced and the process itself are seen as a set of forced steps required to continue working on the project, so people may come up with a way to cheat the system and do the bare minimum to satisfy the organization. Normally, that ends up with useless documentation for human beings.
- The process generates so much output (too verbose) that the developers either don’t have time to read the docs or experience Information Overload, not being able to extract any value from them.
As you can see, this is yet another example that extremes are wrong: you can find problems with and without a Software Architecture process. What I aim to achieve with this guide is that you find a sweet spot in between: you can configure your own lightweight Process, try it, and adapt it until it works for you.
You keep repeating “boilerplate tasks”
In Software Architecture, a good process can help us remove all the extra effort required for repetitive tasks such as:
- Where do I place this design document? What should I include there? Which tools do I have?
- How many tests does this code require? Do I need to document it? Who do I need to ask to include this extra library?
- Who should I invite for a design meeting? Do we really need a meeting? What should I include on the agenda?
- I have a problem to solve in code that looks like a boilerplate task, do we have conventions to solve it? Can I reuse a common pattern?
Sometimes we don’t notice how much time takes, as a whole group, thinking about this kind of questions. However, when you agree on these basic rules and patterns, you can focus on real, creative and fulfilling work. The reasons are simple:
- You know where to find the trace of previous actions (e.g. docs), and what is its content.
- You avoid endless, recurrent discussions about trivial topics (see next section about making decisions).
- You don’t need to switch context continuously when everything is organized the same way.
You don’t have a good decision-making mechanism
I’ve seen many times teams that struggle to make decisions related to their Software Architecture. Other teams make decisions very fast, but nobody follows them later. There is no single reason behind those problems, it’s like a cocktail with several possible ingredients:
- The Dictator. Only one person makes the decisions without consulting others. In this case, it doesn’t matter if the outcome is documented or not. It’s unlikely that the decisions are good since they’re never taking into account multiple perspectives. Besides, the team won’t feel represented so they won’t embrace those decisions. The result is a team that is either feeling frustrated for following rules that they don’t understand or skipping the rules because they feel the decisions don’t make sense.
- The Decision Queue with multiple Workers. The first person who faces a common problem defines the common solution. This is a variation of the first one with same results. If that person is not taking into account other requirements by involving others, the decisions won’t be good.
- The Déjà vu. With this one, we enter into the world of making decisions involving a group of people. The déjà vu happens when you come back to problems that you’ve seen before, and you’re making decisions about a specific topic that was already discussed in the past. There are two variations:
- You discussed the problem in the past but you never made a decision on how to solve it. Normally, this is manifested as a series of meetings that go nowhere, in which the attendees tend to focus too much on the problem but not on thinking of possible solutions and defining actions.
- You discussed the problem in the past, and you made a decision, but there you are again… It might be caused by a badly documented decision or bad communication (a decision was made but nobody knows it). But the reason can also be that some people don’t like the decision and would like more time to argue about that.
- The Tabs vs. Spaces fights. Trivial discussions are devouring your working time. You enter a meeting with the goal of making a decision that is important for the project but somehow you end up consuming most of the time in topics that are minor and should be decided quickly (they can be easily changed later and/or there is no clear preference for one option). Some of these trivial topics, micro-problems attacking your meetings, may also be recurrent (let’s call them micro déjà vu’s).
Having a good process in place will help you deal with these situations and come up with productive outcomes. Surely it won’t remove these issues from the working environment since they’re things that just happen because we’re humans, but a pragmatic process can make a big difference.
The Process Stigma: is an Architecture Process boring?
The very word process may trigger in you a negative feeling. It’s normal: some people (including me) have suffered from extremely boring tasks that were required during the normal software development process.
In the past, I’ve been required to fill in a document of ~10 pages each time we wanted to include a new library as a dependency in our product (even a popular one, such as Guava or Apache Commons Lang). It could take almost one day to fill in the document, plus a few weeks for the document administration to finish. Say four weeks are required before you can use that useful method that will save you write 200 extra lines of code. If you’re under pressure, you’ll forget about the library and put those extra lines in your code, paying a higher price in maintenance and code crappiness. In this case, the process is not only boring but annoying and counter-productive.
You don’t need an ISO norm, going too formal or hiring extra people to implement a process. All you need is a wiki-style platform where you can write the steps to follow to achieve something or the decisions you’ve been making over time. And, as you’ll see in the next sections, you can create a lightweight process, tailored to your needs and easy to maintain and follow.
A good process is like a good recipe. Maybe you copied that recipe from a website and it’s too much detailed and it takes too long to read. Maybe you don’t like spices too much so you remove them from the process. So you modify the recipe and make a list of steps that work for you, that makes you achieve that dish that you love: a great outcome. After some time, you don’t even need to follow the recipe because you know it by heart. But you got there by taking notes and fixing the process, and that’s much more efficient than improvising the steps each time you prepare the dish and trying to remember them the next time.
Process Outcome: The Architecture Guide
The Architecture Guide is an alive, evolving set of documents. It’s the tangible outcome of the Process (even being digital – you can read it). It holds the designs, conventions, and decisions you made as part of the process.
Both the Guide and the Process are important so you shouldn’t focus only on one of them. If you get a perfect Architecture Guide without a good process supporting it, that will be like giving a book to the development team and hoping that they’ll follow it without questions; that’s a top-bottom approach unlikely to succeed. On the other hand, if you have a very efficient process but the results are not properly organized and documented, you’ll experience the déjà vu effect.
The owner and ultimate responsible person for keeping it up-to-date should be the Software Architect(s), but the contributors might be many. Think of the Architect as an editor reviewing and organizing pages created by developers, giving consistency and providing a high level of organization. I know that we as developers (I consider architects as developers too) don’t like to write documentation so it’s hard to get others to contribute; anyhow, you should encourage it.
For the elaboration of this Guide, I strongly recommend you to read the book Software Architecture for Developers (Volume II), written by Simon Brown. In that practical book, you’ll see a detailed description of all the sections that you should include in your Guide and good advice on how to keep it focused on what’s important. It also covers the C4 model, a very useful way to visualize Software Architecture. These are the headings proposed in the book:
- Functional Overview
- Quality Attributes
- Software Architecture
- Infrastructure Architecture
- Operation and Support
- Development Environment
- Decision Log
My recommendation is that you use any kind of document sharing tool already available in your company and set up a dedicated space with these sections as placeholders. Make sure that all project members can see and edit. It should provide changes history so you know what changed in a page, when and who modified it. Link there any existing documentation that you already have and that you consider useful (only if you can keep it lightweight and to the point, try to avoid building a Frankenstein Guide copy-pasting from multiple docs with different styles). As an alternative, you can also create an extra section, Legacy Docs, and index there your old documents. Then you can incrementally build your new Guide using the Process described below.
The Practical Architecture Process
Now that all the required context is clear, let’s have a look at the process structure (the meta), the process steps and the description of its different parts.
Meta: Meetings, Inputs, and Outputs
First, you need to familiarize with the process elements. As you can see in the diagram 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. Anyway, in the meeting descriptions below, I’ll indicate what to include in those sections.
Meta: Architecture Journal and Decision Log
In the headings proposed by Simon in his book (the guide structure shown above), you can see that the last section is named 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 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?
- What were the alternatives? What were the Constraints?
- Why did you choose one instead of the others? (see below 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?
The reasons to keep this 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.
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.
🏁 Vision and Constraints
Let’s start defining the Process Areas with the most important part. Every Software Project has a Vision: an ultimate goal of its existence. An example of this would be a sentence like “Becoming the market leader in rubber-duck e-commerce”. This overall business objective should be paired with an Architecture Vision: how your Software should look like to achieve and support the Business Vision.
The Architecture Vision is extremely important to scope your objectives. Depending on the project, you might want to focus on robustness, performance, agility to make changes, ease of support, etc. Therefore, the process starts with defining these long-term goals.
Listing your Constraints will help you a lot too: do you have a limited set of tools that you can use because there is an existing contract in place? Is the budget too limited? Sometimes this task requires an exercise of humbleness and honesty: do you have the skills that are needed to achieve the objectives? As you can see, most of the constraints are usually related to time, money, knowledge and tools. Writing all these things down makes everything easier since everybody will know the main rules of the game: which parts can change and which others can’t.
The Practical Architecture Process proposes a meeting to extract your Vision and Constraints. After that meeting, you need to create the Architecture Vision and list the Principles that will guide people during development. For that purpose, you need to involve others in the process: that’s the goal of the Agreeing on Principles meeting. Let’s explain these steps in more detail.
👥 Meeting: Vision and Constraint Analysis
Collect all the existing information available about Vision and Constraints of the project. Those can be the Business Plan, a set of presentations, etc. Check if there are gaps or you miss something. Add any other Constraints that are not yet documented but you know they have a big impact on the long-term success. Then, prepare a summary with this information and gaps (if any) to be presented during the meeting.
Business Audience. People who can answer the big questions about Vision and Constraints. There may be many role names that satisfy that requirement, but surely you know who they are in your organization: Project Managers, Product Owners, maybe CEO and CTO if it’s not a big company.
Format and Duration
Keep the duration of the meeting to one hour. Set the goal of the meeting as something like “Align Software Architecture with Vision and Constraints”. Make sure in advance that important people, those who can answer your questions, can attend. Include a brief description of what you want to achieve with the meeting, containing the summary that you already extracted from existing resources (inputs).
Your role in this meeting as Software Architect is to drive the conversation to get the required answers to the questions:
- What are our Vision and Long Term Goals (business)?
- Do we have any constraints (money, time, tools, people)?
- Can we solve those Constraints that are risks for defining a good Architecture? (if this applies to you)
If the Vision and Goals are not clear, try to avoid shallow statements such as “Selling as much as we can” or “We don’t have any constraint as long as we don’t spend too much money”. As an example: if you’re running the rubber-duck e-commerce platform, you want to know if the long-term vision is to provide the best customer service, sell ducks around the world or if offering the cheapest prices are the ultimate goal.
Also, share any concern you may have about risks derived from constraints (e.g. not having access to proper tooling, lack of developers, etc.). Identify together those that can be solved quickly (therefore not being constraints anymore) and create action points for them (who is going to take care of each one and how?).
Write down your notes in an organized way in the Architecture Guide (as you can see above there are dedicated pages for that). Add a new entry to the Journal with the list of actions points (if any) so they’re visible and can be easily followed.
Now, create the Architecture Vision using the project’s vision and constraints as inputs. Which System Quality Attributes are you going to prioritize based on the business input? What type of Architecture are you building to achieve those goals? Are there any other constraints to add from the technical side to the existing ones?
👥 Meeting: Agreeing on Principles
From the output of the previous session (the Architecture Vision and the Business Vision), you should extract some Principles. These are general guidelines for your project that should help you achieve those long-term goals. For example:
- We favor asynchronous calls over synchronous ones
- We do Functional Programming
- We favor libraries that have commercial support
Then, once you have a draft version of the Principles, and the previously-documented Business and Architecture Vision, involve other technical people in the process. The reason why I recommend you not to do this earlier is that it’s always much easier to discuss topics and get to valid conclusions when you have some material already prepared and in front of you – the draft documents.
You want mainly a Technical Audience. You may also want to invite one or two business representatives to help. Given that the goal of this step of the process is defining the Principles that will guide your Architecture, it’s a good idea to involve the people with more experience within the teams.
Format and duration
Schedule a one-hour meeting. Make sure to send all attendees the output from the Vision and Constraints step and the draft document for this meeting, so they can read them in advance, comment, and prepare their questions and concerns. Use the first 15 minutes to present the first version of the Architecture Vision, Constraints and Principles and make sure you refer to the Business Vision and explain how they are aligned. Leave the rest of the time for questions and proposals from others around constructive questions: are there other principles that we should add? Is something maybe not clear enough or too broad? Gather all the feedback.
It’s important that the Principles and the Architecture Vision have enough consensus. As with other topics, try to convince with good reasoning in case the majority is not supporting your ideas and, if that doesn’t change, use some time to think about it because you might be wrong.
Ideally, you can finish this in our hour, but it can take up to two or three sessions to have a proper outcome. Anyway, you can continue with the rest of the Process with only the first version of the Principles, and then iterate to refine it every few weeks.
Use your meeting notes to go over the documents and update them as needed. Go to your Principles page in the Guide and update it based on the feedback. Try to keep it concise, just a list with clearly-defined principles. The rest of your notes with the Who, What, When and Why, should be written down as a new entry in the Journal.
🛣 Architecture Roadmap
After you define the broad topics it’s time to get more specific. Some of the most practical sessions you can have in this process are the Target Architecture Definition and the Roadmap Session. During those, you’ll focus on the next steps to build the Architecture you’re aiming for.
Note that this part involves a lot of thinking and preparation before going to real meetings. First, you need to define your target architecture taking into account all the inputs you have available and your experience and experience from others. You need to consider different alternatives and think of their benefits and their disadvantages for your case. Then, you need to define what are the next steps that you should take in order to achieve the target architecture. For both tasks, it’s important that you get feedback and input from others so you end up with a good consensus. However, it’s also crucial that you prepare all the context in advance so you don’t start discussions with a blank page. If you don’t set up a frame and context to enable discussions, the situation can be hectic.
👥 Meeting: Target Architecture
As mentioned above, this is one of the steps that require more preparation in advance. It consists of one of your main duties as Software Architect: defining the target architecture of the project based on the requirements, the time available, resources, etc. Use the structure of the Architecture Guide to fill in some contents, but don’t restrict yet to a single option. You have to explain, for instance, what are the benefits of going for a modular monolith instead of microservices, and also the disadvantages (remember, this is just an example). Try not to copy general conclusions from books or articles but adapt them instead to your specific environment.
Remember that you should cover not only the target software composition of your project but also its infrastructure, the Continuous Integration setup and how Deployment will look like. You don’t need to be very specific at this point but it’s essential that you are realistic and pragmatic when listing the alternatives. This is not an easy task nor something that a single person can do efficiently so try to do this collaboratively with other people.
Take also into account that you won’t be accurate at the beginning. That’s not a problem, your Target Architecture may evolve along time after you try things and become aware of unexpected problems or constraints, or you figure out simpler ways of building your Software.
Use diagrams to represent the different options and how you plan to organize your components, infrastructure, etc. They are easy to understand and will serve as a base for possible discussions. Again, I recommend you to use the C4 model from Simon Brown (available online but also explained in his book) since it’s way simpler and clearer than other documentation methods. If you use this model, prepare draft alternatives for Level 1 (System Context) and 2 (Container) diagrams.
For this meeting, you need mainly a Technical Audience with expert representatives. However, having at least one person from the pure Business side may be very appreciated. That person might help you keep the focus on how the different alternatives are directed to build the target requirements.
Format and Duration
Keep the duration of the meeting to 90 minutes maximum. Aim to finish it in one hour. For this meeting, it’s extremely important that the attendees receive all the prepared diagrams and descriptions in advance, so they go through them before the meeting. Send reminders one or two days before the meeting to make sure they read the docs and prepare their questions.
During the meeting, use the first 15 minutes to go over the different options, their pros, and cons. Express your opinion about what you believe it’s the best option and why. Then, because it’s almost impossible that your diagrams/documentation are 100% clear, use some time just to answer questions about the different options.
After the questions, leave some time so others can express their concerns and propose other ways to design parts of the system. However, it should be clear before the meeting that, if someone has a completely different approach for the Target Architecture, they should prepare the same diagrams/documentation as you did before that session.
In some cases, the discussion may become difficult. For instance, let’s say you’re proposing to start with a modular monolith and split later when needed. Some people may argue that you might be trapped with a monolith forever, and defend a position of building microservices from the beginning. That’s a normal discussion, but try to keep always the conversation around a proper rationale: advantages, disadvantages, constraints and overall plan for your specific situation. In that example, the microservices approach should have been analyzed before the meeting, taking into account its impact on continuous integration, deployment, ways of working within teams, etc. Part of your work as Architect is to make people aware of other side aspects of Software Architecture that affect the decisions you need to make: how do you plan to get there? Are there enough developers to work on that? Do we have the proper tools? Does it make sense for our specific use case and requirements? Is it the best option for our long-term vision goals? There will be occasions in which you just need to make a decision and move forward, not to get stuck in repetitive discussions.
As usual, you need to write a new entry in the Architecture Journal. Then, you should revisit your Software Architecture page (e.g. C4 diagrams and descriptions) and modify them accordingly, based on the feedback you got and the decisions you made during the meeting.
You may need to repeat this session two or three times until you get to a valid, sufficiently-defined Target Architecture to start with. Don’t try to extend the duration of the session to get results sooner since this is the kind of meeting that doesn’t go better when it lasts longer.
👥 Meeting: Short-Term Goals
First, you need to have the Target Architecture defined before this session. Having that as your first input, you need to combine it with the Functional Roadmap: what are the features that you’re planning to build first? Ideally, that roadmap is a bit flexible and can be modified depending on the Architecture requirements but, even if not, it’s a valuable input.
If you’re not starting from scratch, you should use as input the list of topics that could significantly change your Architecture for the better. If you don’t have anything yet, create a list of tasks that you need to accomplish. Think of this kind of tasks: automation of build steps to reduce manual interaction, design module boundaries, create (or adopt) code conventions, extract part of common logic to a library, etc.
Technical Audience. If the task is not purely about Architecture (for instance designing module boundaries), then invite someone with Business knowledge.
Format and Duration
These sessions should take 60 minutes maximum. Start with the goal of the meeting: to prioritize and pick the next Architecture work items. Present the list of tasks that you already identified and ask others to contribute to the list.
Try to use a whiteboard and sticky notes to allow for better organization. First, let everybody list what they think that are the most important tasks to do. Then, use dot-voting to identify what are the most valuable. After everybody has voted, organize the stickers in three columns that represent how easy those tasks are in terms of complexity and time: easy, medium, hard. Decide where to place each task as a group.
Once you have all the tasks in the three columns and with their respective dots, it should be easy to identify the quick wins: all of them with a high score placed in the “easy” column. Anyway, you can’t forget all the other ones, especially those with many dots. Try to pick one of the high-scored hard ones at a time. Don’t forget to take a picture of the whiteboard so you can upload it later to the session notes.
Agree on the first 3 to 5 topics to work on and then assign (as a team) action points: who can work on what? If they’re not ready to be picked but they need some further analysis, who can take care of that? As usual, write those action points down.
The frequency of these sessions depends on your needs, but it may be good to start with one per month and then adapt.
After the session, write down the meeting notes including the action points and the whiteboard picture. Plan the follow-up session so you don’t forget about it. Add a new entry to the Architecture Journal pointing to those meeting notes. Share it, and ask for possible feedback.
Now you need to coordinate with Project Managers (or Product Owners) how those items are going to be properly refined and taken inside the Sprints (or any other unit of planning that the teams have, in case you’re not doing Agile). Some of these items are purely technical (for instance, let’s say you want to extract all the logs to a common aggregator), yet it’s vital that they are part of the planning together with other feature-related stories. If you don’t manage to find a good balance between them, your project will most likely end up with no proper architecture at all, just a bunch of software blocks that at some point will become unmaintainable and very expensive to evolve.
✅ Decision Making
This part of the process is the one that will help you make decisions. Note that you don’t need to use this set up for every decision you need to make, but it’s useful to apply this pattern whenever the choice you want to make has an impact on multiple parts of your system and/or multiple teams.
Furthermore, you don’t need to create meetings for each of the steps mentioned below. Depending on the size and importance of the decision, you may want to combine them into a single one. If you prepare well, you can go to a one-hour meeting and explain a given problem, study the alternatives and then make your decision. When you get enough experience, you can even make it in less time. Low-impact decisions can even be made on-the-fly after a short discussion. In any case, if it’s relevant enough, better follow the steps described below in terms of writing down the inputs and outputs.
If your project has several teams, you can also split decision making per team when that makes sense. Especially if the problem is likely to impact only to a part of the project.
👥 Meeting: The Problem Description
First, describe the problem you’re facing: What do you want to solve? It may be a functional or technical challenge, e.g.: design and implementation of a payment workflow, bad performance with database queries, splitting the system into smaller modules, etc.
It’s very important that you also highlight why they are a problem. It might be obvious but sometimes we make the big mistake of classifying as a problem something that really isn’t. A simple, clear reason will suffice when describing the problem, for example: “we want to identify in which part of the flow our users are to target them better”, “we’re wasting at least one hour per day waiting for the database”, “we can’t evolve our code efficiently because it’s too tangled”, etc.
Besides, you need to extract as well what are the specific constraints when looking for a solution. Is it an issue that is extremely urgent so it needs a quick fix? Are there only limited people available to work on that?
Technical Audience and, if the problem is related to functionality, you’ll need Business people to explain it and to be asked if some alternative solutions are valid.
Format and Duration
An hour should be more than enough to start with. When you get better at defining problems you can try to combine this session with the exposition of alternatives and making decisions.
Take into account that a common pitfall in Software Development is investing too little time in the problem analysis and switching too quickly to the search of solutions. Don’t do that: try to understand the problem as best as you can and get all the requirements and constraints. Visualize what are the possible problem scenarios, but at the same time don’t spend too much time in detailing corner cases.
Remember: the best outcome you may get from this meeting is noticing that you don’t need to do anything to solve that problem, or identifying it as not being a problem at all.
During this meeting, use the whiteboard as much as possible. We tend to get distracted when others describe abstract concepts that are easier to understand when are mapped to boxes and arrows. Just use the tools you have. I’ve seen hundreds of lines of useless code written only due to the lack of a good description of the problem.
There should be a Journal Entry with pictures of the whiteboard (if any) and a summary about the problem. And then, it’s time for you and the rest to start thinking about solutions.
👥 Meeting: Alternative Solutions
The problem, described in the Journal Entry. Also, the proposed solutions should be sent in advance by their creators so everybody can have a look and ask questions in advance.
Ideally, the same one that helped to define and scope the problem.
Format and Duration
One hour maximum, try to keep it shorter.
Your main objective here should be to keep things as simple as possible. Remember that Simple is Hard so most probably the fanciest solutions you can think of are not the best ones.
On the other hand, you shouldn’t sacrifice quality in favor of simplicity so don’t confuse a crappy solution with a simple one.
This session should focus on the different available solutions and what would imply to implement them. Each person presenting a solution should cover how it solves the problem without getting into too much detail. Once the overall idea is clear, that person should provide a brief description of what would be the steps (tasks) to get that solution working. By doing this, you avoid putting too much effort into considering solutions that are unfeasible or require too much research.
A list of different alternatives to solve the problem. It might be that there is only one way to solve it, then the decision becomes much easier.
👥 Meeting: Decision Making
The problem description, its constraints and the different alternatives to solve it (outputs from the previous process steps).
Same as involved in the previous steps of defining the problem and alternatives.
Format and Duration
The art of making decisions is difficult but it will become an easy task if you did the previous steps correctly. Knowing your constraints and the available options, it should be possible to identify the best way to move forward.
This session should be limited to 30 minutes maximum but, ideally, it may be combined with the previous one and even with the problem definition when that’s possible. Anyway, you shouldn’t go over one hour when combining these meetings.
Your goal during this meeting is to use all the information available to make a decision and plan the next steps. Try to get a good consensus, although sometimes it won’t be possible. In those cases, people should just understand that not everybody is going to be happy about all the decisions that are made.
Note that you don’t need to choose always the best solution in terms of quality. You may know perfectly that you go for a non-optimal solution but that can be still the best alternative given the constraints and your knowledge at that time. What is important in each case is that you write down why you chose that option.
Use a Journal Entry to document the decision you made and the reasons behind it. If there are remarks in terms of constraints that affected your decision, it’s critical that you write them down too.
Share this decision with the rest of the team and encourage others to respect it and don’t diverge from it. Once you make a decision you shouldn’t be reconsidering it or discussing it all the time: that’s very frustrating, especially when you dedicated a lot of effort to analyze all the possible options.
The better you become at using this process, the better your Decision-Making mechanism will be. When people get used to how decisions are made, they’ll know what is the time to propose new ideas or argue about specific alternatives, and when is time to just accept the decision no matter if they don’t think that’s the best option.
Even though the decisions should be respected and followed for a while, you can always revisit these decisions when new information is available or constraints change. But the change should be always backed up by a good plan.
The Process as a Baseline
I created this Practical Process compiling some experience from my last years. That fact, obviously, doesn’t make the process a magic solution for every project and organization. What it worked for me, may not work for you. There are many variables such as the company culture, the country working-culture, your soft skills, the support from others to implement the process, etc., that can change completely your experience while trying this out.
Therefore it’s important that you take this process as a reference and you adapt it to your case. Maybe you want to get rid of some steps or introduce some additions, for example. If you do so, I would love to read your feedback.
Continuous Evolution and Effort
The steps in this process are designed to be repeated over time. Software projects are continuously changing so you need to adapt to that as well. That means that you should revisit your documentation and summon people every now and then to refine the Vision, Constraints, Goals, Roadmap, and Decisions. You will require a constant effort to keep all the outputs in order and events in place.
After introducing the process you need feedback from others to help you make a success of it. Ask others to be honest about what they think of it and how you could improve it. The good feedback is the one that hurts, but it will help you to be constantly growing as a Software Architect.
Let me know how it goes
This document will evolve as I learn new ways of doing things. As a living document that is, I can use your input if you consider that something doesn’t work for you or needs clarification.
If you have feedback for me I’ll also appreciate it (even if it hurts).