Gathering the right information to design high-quality software

Fantastic! You’ve just started a software development project. Now, it is time to use all your knowledge to deliver the best software you can. Your first question is probably – How do I start? Well, as a software architect, you are going to be the one to answer that question. And you can be sure that your answer is going to evolve with each software project you lead.

Defining a software development process is the first task. This is generally done during the project planning process, or it might happen before it starts.

Another very important task is to gather the software requirements. No matter which software development process you decide to use, collecting real user needs is part of a difficult and continuous job. Of course, there are techniques to help you with this, and you can be sure that gathering requirements will help you to define important aspects of your software architecture.

These two tasks are considered by most experts in software development as the keys to success at the end of the development project journey. As a software architect, you need to enable them so that you can avoid as many problems as possible while guiding your team.

Understanding the requirements gathering process

There are many ways to represent the requirements. The most traditional approach consists of you having to write a perfect specification before the beginning of the analysis. Agile methods suggest instead that you need to write user stories as soon as you are ready to start a development cycle.

Remember: You do not write requirements just for the user; you write them for you and your team too.

The truth is that no matter the approach you decide to adopt in your projects, you will have to follow some steps to gather requirements. This is what we call requirements engineering.

Figure 1.7: Requirements engineering process

During this process, you need to be sure that the solution is feasible. In some cases, the feasibility analysis is part of the project planning process too, and by the time you start the requirements elicitation, you will have the feasibility report already done. So, let us check the other parts of this process, which will give you a lot of important information for the software architecture.

Detecting exact user needs

There are a lot of ways to detect what exactly the user needs for a specific scenario. This process is known as elicitation. In general, this can be done using techniques that will help you to understand what we call user requirements. Here, you have a list of common techniques:

• The power of imagination: If you are an expert in the area where you are providing solutions, you may use your own imagination to find new user requirements. Brainstorming can be conducted together so that a group of experts can define the user needs.
• Questionnaires: This tool is useful for detecting common and important requirements such as the number and kind of users, peak system usage, and the commonly used Operating System (OS) and web browser.
• Interviews: Interviewing the users helps you as an architect to detect user requirements that perhaps questionnaires and your imagination will not cover.
• Observation: There is no better way to understand the daily routine of a user than being with them for a day.

As soon as you apply one or more of these techniques, you will have great and valuable information about the user’s needs.

Remember: You can use these techniques in any situation where the real need is to gather requirements, no matter whether it is for the whole system or for a single story.

At that moment, you will be able to start analyzing these user needs and detecting the user and system requirements. Let us see how to do so in the next section.

Analyzing requirements

When you have detected the user needs, it is time to begin analyzing the requirements. To do so, you can use techniques such as the following:

• Prototyping: Prototypes are fantastic to clarify and materialize the system requirements. Today, we have many tools that can help you to mock interfaces. A nice open-source tool is the Pencil Project. You will find further information about it at https://pencil.evolus.vn/. Figma (https://www.figma.com/) is also a good tool for prototyping and they provide a starter pack that is free forever.
• Use cases: The Unified Modeling Language (UML) use case model is an option if you need detailed documentation. The model is composed of a detailed specification and a diagram. Lucidchart (https://www.lucidchart.com/) is another good tool that can help you out with this. You can see the model created in Figure 1.8:

Figure 1.8: Use case diagram example

While you are analyzing the requirements of the system, you will be able to clarify exactly what the user’s needs are. This is helpful when you are not sure about the real problem you need to solve, and it is much better than just starting to program the system and hoping for the best. Time invested in requirements analysis is time invested in better code later.

Writing the specifications

After you finish the analysis, it is important to register it as a specification. The specification document 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.
• You need to classify each requirement.
• Use simple future tense to represent each requirement:
  • 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.

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 requirements 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 probably 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.

This is when you present all the prototypes, documents, and information you have gathered. As soon as everybody agrees with the specification, you are ready to start studying the best way to implement this part of your project.

It is worth mentioning that you might use the process described here for either the complete software or for just a small part of it.