Writing the specifications

After you finish the analysis, it is important to register it as a specification. The specification docu- ment
can be written using traditional requirements, or user stories, which are commonly used in agile projects.

A requirements specification represents the technical contract between the user and the team. There are
some basic rules that this document needs to follow:

• All stakeholders need to understand exactly what is written in the technical contract, even if they are not
technicians.

• The document needs to be clear.

Bad example: A common user registers themselves

Good example: A common user shall register themselves

Ambiguity and controversy need to be avoided.

Some additional information can help the team to understand the context of the project they are going

to work on. Here are some tips about how to add useful information:
 ●

Write an introductory chapter to give a full idea of the solution

Create a glossary to make understanding easier

Describe the kind of user the solution will cover

Write functional and non-functional requirements:

• Functional requirements are quite simple to understand because they describe exactly what the software will do.
On the other hand, non-functional requirements determine the restrictions related to the software, which
means scalability, robustness, security, and performance. We will cover these aspects in the next section.

• Attach documents that can help the user to understand the rules

If you decide to write user stories, a good tip to follow is to write short sentences representing each
moment in the system with each user, as follows:

As <user>, I want <feature>, so that <reason>

This approach will explain exactly the reason why that feature will be implemented. It is also a good tool
to help you analyze the stories that are most important and prioritize the success of the project. They can
also be great for informing the automated acceptance tests that should be built.
Chapter 1 19

Understanding the principles of scalability, robustness, security, and

performance

Detecting requirements is a task that will let you understand the software you are going to develop.
However, as a software architect, you must pay attention to more than just the functional requirements for that
system. Understanding the non-functional requirements is important, and one of the earliest activities for
a software architect.

We are going to look at this in more detail in Chapter 2, Non-Functional Requirements, but at this point, it
is important to know that the principles of scalability, robustness, security, and performance need to be
applied for the requirements gathering process. Let us look at each concept:

Scalability: As a software developer, globalization gives you the opportunity to have your solution
running all over the world. This is fantastic, but you, as a software architect, need to design a
solution that provides that possibility. Scalability is the possibility for an application to increase its
processing power as soon as it is necessary, due to the number of resources that are being
consumed.

Robustness: No matter how scalable your application is, if it is not able to guarantee a stable and
always-on solution, you are not going to get any peace. Robustness is important for critical solutions,
where you do not have the opportunity for maintenance at any time due to the kind of problem
that the application solves. In many industries, the software cannot stop, and lots of routines run
when nobody is available (overnight, during holidays, and so on). Designing a robust solution will
give you the freedom to live while your software is running well.

●
 Security: This is another really important area that needs to be discussed after the require- ments
stage. Everybody worries about security, and different laws dealing with it are in place in different
parts of the world. You, as a software architect, must understand that security needs to be provided
by design. This is the only way to cope with all the needs that the security community is discussing right
now.

Performance: The process of understanding the system you are going to develop will proba- bly
give you a good idea of what you will need to do to get the desired performance from the system.
This topic needs to be discussed with the user, to identify most of the bottlenecks you will face
during the development stage.

It is worth mentioning that all these concepts are requirements for the new generation of solutions
that the world needs. What differentiates good software from incredible software is the amount of
work done to meet the project requirements.

Reviewing the specification

Once you have the specification written, it is time to confirm with the stakeholders whether they
agree with it. This can be done in a review meeting or it can be done online using collaboration
tools.