diagram of good requirements defined

FIRMWARE & SOFTWARE PROCESSES & BEST PRACTICES —> Part 1: Requirements

requirements image for firmware / software project

Requirements are like roads on a map. Requirements are what defines the landscape, the starting point, and the destination. Without a good map, you won’t know whether you should follow the river or go through the mountain pass – and where are you going anyway? How do you know when you’ve finished your journey or if you arrived at the correct destination without a clearly defined end point? By clearly defining what the software is going to do, and how the system is expected to perform, we can easily see the landscape and know our destination. Let's learn more about how well-defined requirements play a role in the success of a firmware/software project.

Introduction

Requirements are critical to the success of a project. Good requirements represent a clear understanding of the customer’s needs. Communication is critical in order to understand what the project requires. Requirements are the medium of this communication. A good firmware/software development team is highly adept at tailoring the amount of detail and documentation to the scope of the project. At times, simple user stories suffice to define requirements, whereas some projects require more details and documentation.

In addition to functional requirements that derive from user stories and use cases, there are often business requirements. In most cases, a customer will know their business requirements and be able to clearly communicate them. It is nevertheless important to verify that functional requirements are aligned with business requirements. Another very important set of requirements to define is acceptance criteria. These requirements inform the testing of the software and ensure that deliverables are met.

Defining good requirements is essential to getting a firmware or software project started. Why do you need stated requirements before development begins?

How do you start your journey? How can you be sure that you are on the right path? How do you know that you’ve finished your journey and arrived at the correct destination?

If you don’t know where you are going, any road will get you there.

– Lewis Carroll

Requirements can come from many sources. Sources of requirements include the following:

  • Compliance Matrix,
  • Written and verbal conversations with customers,
  • Developers,
  • User manuals,
  • Previous releases,
  • Existing test plan, test cases, final acceptance test (FAT),
  • Issue tracking system:
  • Defect reports,
  • Change requests.
  • Other sources.

User Stories and Case Studies

Developing software isn’t like the Field of Dreams in which you “build it and they will come.” You must build what meets the needs of the customer. Defining software requirements is how to take big ideas and turn them into a set of goals. The accomplishment of these goals is the deliverable product. One way to define software requirements is to craft a vision statement with the customer, brainstorm user stories, and derive use cases from them. A user story and the use cases, which are the children of the user story, are two tools that are used to explore, elaborate, and ultimately define firmware/software requirements.

Some software developers dream of receiving a list of clear and concise requirements up-front that they can then implement. However, if a customer doesn’t have a clear idea of what these are, the SIGMADESIGN firmware/software development team provides the expertise to help them discover what they really need. As consultants, we understand that you don’t always know how to define requirements and you may not have thought of every aspect. We help you work out all the details that lead to the definition of good requirements in order to create a successful product.

A user story is a short note that captures what a user does or needs to do. A set of user stories describes the functionality of software from the perspective of the user. A user story typically follows a pattern of:

As a <role>, I want to be able to <function of system>, so that <goal> can be achieved.

A simple statement like this helps to start the conversations with the customer that flesh out the details. The ideas that emerge from these conversations can then be elaborated in use cases.

A use case captures the details of the ideas that are revealed in the user story discussions with the customer. It defines the interactions between the system and one or more actors which can be people, other systems, or both. Use cases specify all the possible scenarios by describing the needed behavior of the system and how that behavior is achieved. Software requirements can then be distilled from the use cases.

Here is an example of a use case leading to a set of requirements:

User_1 needs to login to System_1.

  • The Login dialog box shall contain fields for the user to input their user name and password.
  • The user must have a valid account with a user name and password in order for the system to return a result of VALID for a login attempt.
  • The system shall validate the user name and password.
  • The system will return a result of VALID or INVALID for every attempted login.
  • If the system is offline, the default result for any login attempt is INVALID.

Characteristics of Good Requirements

At the inception of a project, a high level set of needs to be implemented is discussed in the form of user stories and use cases. A good, well defined software requirement can easily be traced back to use cases and user stories.

Poorly defined requirements can get us lost and can lead to:

  • Product defects,
  • Scope creep that negatively affects budget and schedule,
  • Potentially poor user interface design and ergonomics which results in lower productivity,
  • Reduced developer productivity as a result of having to continually update/refine requirements with the customer,
  • Time-consuming and costly rework,
  • Difficulties with solution integration.

Good requirements include these key attributes that help to define the landscape:

  • They contain the right level of abstraction,
  • They are factual and grammatically correct,
  • They are feasible within constraints,
  • They are atomic and do not contain multiple elements,
  • They are necessary for the deliverable,
  • They are testable,
  • They must be unambiguous and easy to interpret,
  • Each requirement can be viewed independently,
  • They are clear and understandable,
  • They are binding,
  • They have unique identifiers.
diagram of good requirements defined

For example, the “right level of abstraction” bubble in the diagram means that good requirements are abstracted from the implementation of the use cases. The requirement is clearly stated and does not contain unnecessary design or implementation details. Here is an example of a good requirement that is abstracted from a high level set of needs: After an unsuccessful login attempt, the user shall be locked out of the system for 30 minutes. Our team has helpful examples of each one of these attributes included in the diagram that help in customer discussions.

New Requirements

It’s important to acknowledge that you cannot anticipate everything in advance. An iterative approach to solving problems saves time and keeps development on track. As the product is developed, new information comes to light which can change requirements or lead to new requirements. Even if requirements change, or new ones are necessary, the overarching vision of the project should not change. It is equally important to maintain the scope of a project in order to deliver a quality product. A “requirement” that is out of scope is not really a requirement for the project, even if it is has validity.

Conclusion

Requirements are the medium that is used to convey the needs of the customer to the development team. Requirements help define the map that tells you where you are going and how you know when you’ve arrived. By defining what the software is going to do, and how the system is expected to perform, we can clearly see our map and know where our destination is (and envision product success). At SIGMADESIGN we know how to balance the trade-offs to achieve the most efficient implementation of the requirements, which is the ultimate goal.


You can read the introduction to this series here.