Read and Understand Architectural Design Specifications with Agile

If you were to build a house, you would start by setting the requirements based on the features you want the house to have: size, number of rooms, flooring materials, etc. The next step would be to hire an architect to create a design that would capture your requirements, which would result in a house layout and things like floor plans, electrical schematics, etc. For an engineer building the house, although the requirements are important to understand the vision behind the project, the design specifications are what give the concrete details of what exactly is to be done, and therefore what matters the most from the perspective of the engineer (who maybe doesn't care that much about what you really want).

In the traditional software world, things are not very different. An architectural design specification is a technical document that describes how a software system is to be developed to achieve the goals described in the requirements. It's analogous to the house plans. It is the most crucial piece of documentation for the developers as it lays out what exactly is to be built down to the technical details. Traditionally, due to the high level of fine-grained details that go into the design, this stage of the development was very costly and time-consuming.

In the Agile world, requirements take the form of user stories, which, when refined to include the system design details, also encapsulate the specifications. User stories capture much more accurately, and with much less formality, what the real requirements and desired functionalities are. Although it may create room for gray areas and subjective interpretations, this user-centric approach usually leads to better end products. There's a reason one line of the Agile manifest reads, "Working software over comprehensive documentation," and it is because comprehensive documentation is not nearly as important as getting things right by listening to the users.

In this guide, we will explore how to reason about architectural design specifications in Agile.

In Agile, requirements give way to the more user-centric user story, and the responsibility for refining the user stories and drafting out details is shared by the product owner and the developers in the team. This is only possible thanks to a shared understanding and empathy towards the end users that is central to Agile culture. That shared understanding is what enables the product owner to focus on high-level goals while all the low-level design and implementation details can be laid out by the development team.

Reaching a shared understanding should therefore be a high priority in any Agile project, starting at the early stages. While it is hard to know when this goal has been achieved, since "understanding" can be highly subjective, you should be confident that you're getting there if:

1. Your team has enough customer context, i.e., they know who the customer is.
2. Your team knows what they're building, i.e., what problem they're solving and what the end product should look like.
3. Your team understands why they're doing this, i.e., what are the business goals, the vision, and the motivations behind the product.

To be clear: the team really means the entire team, not just the product owner. Once a shared understanding is established, everything falls into place: aligning functional and non-functional requirements, refining user stories, and prioritizing the backlog become a natural, ongoing team effort as opposed to a monumental one-time activity carried out by a single individual.

Because in Agile practices the requirements are captured into user stories and formulated from the end user's perspective, the design efforts should be consistent with that perspective from the start. It is therefore important to adopt customer personas when designing the system to ensure that the system will deliver the expected value.

Making sense of the architectural design comes down to the following steps:

• Identify assumptions: What are the technical and business assumptions being made? What assumptions about the user are being made?
• Identify the technical and business constraints: What are the technical constraints everyone should be aware of? Are there, for example, infrastructure capacity limitations that influence the overall design? Language and tooling constraints? Standards and regulatory compliance to adhere to?
• Identify the non-functional requirements: What are the "hidden" qualities of the system that belongs to the design?

The FURPS+ acronym, devised by HP, represents a model for classifying the various attributes of software quality. Albeit somewhat dated, FURPS+ still stands as a very useful framework for software development even in Agile culture. It can be used as a way to elicit requirements from Agile user stories. The acronym stands for:

• Functionality: the functional requirements and the capabilities of the software product. This is what the software is supposed to do and what will be more directly expressed by the end user
• Usability: the aesthetics and the human factor, including things like responsiveness and consistency
• Reliability: the availability and stability of the system
• Performance: the speed, efficiency, capacity, etc.
• Supportability: the maintainability, extensibility, and things like repair speed of the system

Except for the "F" part of the acronym, everything else relates to non-functional requirements, which is why a significant amount of time and effort should be dedicated to understanding them. Once again, the shared understanding is an important pre-requisite, as some of these qualities can only be properly captured into the design by assuming the user's perspective and empathizing with the user's concerns.

The '+' part of FURPS+, added as a revision to the original framework (FURPS), includes some of the technical and business constraints mentioned previously.

One final note about architectural design is that, as with everything else in Agile, it should not be written in stone and treated as a non-negotiable contract. The end product is the contract, and the design can evolve as many times as necessary to accommodate changes—be it technical changes, such as new constraints derived from a platform update for example, or just a change in perspective because someone realized a slightly better way of doing something to achieve the user's goals. Hence the importance of interpreting architectural design specifications through the broader perspective of a shared understanding and through the lenses of frameworks such as FURPS+ that include system qualities that are essential for building good software products.

Requirements and specifications in Agile are no longer the intimidating pieces of documentation that they used to be in the old days. And they're no longer one man's job either, but a team effort that is based on a shared understanding of the user's goals and on the collective wisdom of the team. They take the form of user stories, which assume the user's perspective and express real concerns as opposed to untested assumptions of what they are.

Understanding the requirements and design specifications are therefore not a skill to be practiced only by product owners, but by every member of an Agile team on an ongoing basis. Getting the design right will almost certainly pave the way for a successful product.

If you're feeling confident that your team has a shared understanding of user's goals and a general idea of the functional and non-functional requirements to aim for, check out this guide: Refine user stories and acceptance criteria with Agile.

You can also check out this related course, especially if you work with Microsoft Azure: Microsoft Azure Developer: Aligning Functional and Non-functional Requirements