Preparing a Software Architecture Roadmap

Preparing a Software Architecture Roadmap

Architecture Roadmap

This page is part of the guide The Practical Software Architecture:

  1. Software Architecture Issues and Solutions
  2. The Process Overview
  3. Documenting Software Architecture
  4. Vision, Principles, and Constraints
  5. Preparing the Roadmap
  6. Decision Making
  7. Conclusions

Description

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

Inputs

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.

Audience

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.

Outputs

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

Inputs

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.

Audience

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.

Outputs

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.

Continue to the next section: Decision Making in Software Architecture