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
Table of Contents
Let’s start defining the Process Areas with the most important part. Every Software Project has a Vision: the 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:
- Favor asynchronous calls over synchronous ones
- Do Functional Programming
- 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.
Continue to the next section: Preparing the Roadmap