Defining Requirements

Posted on November 6th, 2021

Part of Notes on Software Design

The requirements for a software application are affected by its purpose, focus, and stakeholders.

Starting with purpose, think very generally: are we (helping to) solve a business, scientific, or technical problem?

From its purpose, the focus of the overall application can be considered:

• Data
  • Traditional database-oriented systems
  • Normal for business applications
• Engagement
  • Decentralised systems which integrate together
  • Facilitate and orchestrate the user's experience
  • Seamless interaction between each other, e.g., Facebook/Instagram cross-over
  • Social media platforms for example
• Insight
  • Support for customer experience through consumption, collection, and analysis of data
  • Gathered from data- and engagement-focused systems

From its focus, the role required within its creation team can also be considered:

• Technical
  • System architect
  • Designer
  • Developer
  • Tester;
• Business
  • Business analyst
  • Domain experts
• Management
  • Project managers
  • Programme managers
  • Team leaders

Lastly, its stakeholders can further influence its requirements; an application with an outsourced maintenance team needs to be securely & safely maintainable by an outsider by design.

Sources

The requirements for an application may be a solution; in the business world, it could be an entire aspect of the system as a whole like data analytics. This also applies at a lower level, e.g., persisting data could be implemented using a database or configuration files.

Functional Requirements

These describe what is solved by the application, i.e, the point of the software. Descriptions can be from a number of perspectives, ideally personas, to address five main aspects...

How — the business functionality

• What the system has to do under-the-hood
• Captured directly, e.g., with a use-case model
• Captured indirectly, e.g., with a business process model

Who — its users

• How competent are they?
• Do they have accessibility requirements?
• (Personas may also define these requirements)

Where — its users in a context

• How do the they access it? Browsers? Mobile app?

What — the data

• Does the system store all information itself?
• Is any data resourced from elsewhere?

With — integrations

• What the system has to do with other systems
• IT , e.g., a payment gateway for an ATM
• Human, e.g., a user-friendly input device for PINs

Non-Functional Requirements

Non-function requirements consider everything else; think expectations of usage, characteristics.

Constraints

Non-functional requirements which cannot be changed.

Technical constraints are self-explanatory. For example, a project for a large organisation replacing a legacy system would need to be compatible with their deployment platform(s); the new system can demand a new deployment mechanism.

• Legacy Integration
• Development Skills
• Existing Infrastructure
• IT Standards
• Implementation Constraints

Business constraints are real-word factors which effect the creation of the solution. Differences in data protection regulations between countries will determine how the data must be secured.

• Time
• Resource
• Scope
• Risk Willingness
• Regulatory
• Geographic
• Organizational

Qualities

Expectations of the application. Quality requirements will be appear similar to constraints, but they are negotiable by-nature.

Qualities may be drafted from the usage-context of the application (implicit), like performance. They may also be provided by the customer/stakeholder (explicit).

Runtime qualities (or observable qualities) provide a value to the user, meaning they can be empirically tested. Is the system actually available 24/7? Are page loads quick?

• Performance: without this, users won't be able to use the system
• Capacity
• Availability: without this, users will stop using the system
• Security: without this, 'users' will stop the system being used
• Systems Management
• Usability
• Accessibility

Non-runtime qualities (or unobservable qualities) cannot be measured easily. For example, disaster management: it's quite hard, and fairly immoral, to simulate an earthquake.

• Portability
• Maintainability
• Manageability
• Scalability
• Data Integrity
• Environmental
• Efficiency
• Reliability

Documentation

Firstly, some rules of thumb:

• Use complete sentences
• Identify requirements with a unique reference, e.g, ID
• Be clear, concise, and explicit (avoid ambiguity, jargon)
• Do not make false promises, e.g., "100% reliable"
• Define success/acceptance criteria
• Ensure they are measurable and testable
• Reference supporting material, instead of duplicating information

Phrasing

The M.O.S.C.O.W acronym helps with phrasing a requirement. I still don't know where the first 'O' comes from.

• 'Shall', 'Will', and 'Must' indicate mandatory requirements
• 'Should' and 'Might' indicate optional requirements
• 'Could' indicates desirable requirements

Guideline

The S.M.A.R.T mnemonic helps to ensure all information for a requirement is provided. Lets start with a basic, undeveloped requirement:

The system should allow a visually impaired elderly person to upload health parameters.

Specific Unambiguous, consistent and be at the appropriate level of detail.

R001: The system should have a higher font screen in the internet application to allow a visually impaired elderly person to upload blood pressure and pulse rate.

Measurable Possible to verify a requirement has been met so include success criteria.

R001: The system should have a higher font screen compliant to Accessibility Requirements for People with Low Visionin the internet application to allow a visually impaired elderly person to upload blood pressure and pulse rate.

Attainable Technically feasible and be within the art of the possible (also known as achievable).

R001: The system should have a higher font screen compliant to Accessibility Requirements for People with Low Vision in the internet application to allow a visually impaired elderly person to upload blood pressure and pulse rate, at least 90% of the time, and assuming all network services and interfacing applications are operating as defined in the Project Assumptions & Dependencies.

Realisable Realistic given all the constraints defined (also known as repeatable).

R001: The system should have a higher font screen compliant to Accessibility Requirements for People with Low Vision in the internet application to allow a visually impaired elderly person to upload blood pressure and pulse rate, at least 90% of the time, and assuming all network services and interfacing applications are operating as defined in the Project Assumptions & Dependencies.This requirement will be delivered on time provided all dependencies on infrastructure and resources are resolved as per the plan outlined in the Project Assumptions & Dependencies.

Traceable Linked from conception through specification, design, implementation and test.

R001: The system should have a higher font screen no smaller than Arial 28px, compliant to Accessibility Requirements for People with Low Vision in the internet application to allow a visually impaired elderly person to upload blood pressure and pulse rate, at least 90% of the time, and assuming all network services and interfacing applications are operating as defined in the Project Assumptions & Dependencies. This requirement will be delivered on time provided all dependencies on infrastructure and resources are resolved as per the plan outlined in the Project Assumptions & Dependencies.

Testable There must be acceptance criteria that aligns with expected business value and converted to a specific test condition.

Representations

Requirement documentation can be very complex and thus difficult to read. By decomposing requirements and expressing them in human-readable formats, the subsequent processes (design, development, testing) can be tackled more easily. It also reduces the likelihood of lost/misinterpreted requirements.

Use Cases

A use case describes how a system will be used, either though a list of actions or event steps by considering:

• Actor — Anyone or anything using the system
• Stakeholder — Someone or something with vested interests in the behaviour of the system
• Primary Actor — Stakeholder who initiates an interaction with the system to achieve a goal
• Preconditions — What must be true or happen before and after the use case runs.
• Triggers — The event that causes the use case to be initiated.
• Main Scenarios — Use case in which nothing goes wrong.
• Alternative Paths — These paths are a variation on the main theme. These exceptions are what happen when things go wrong at the system level

User Stories ❤️

A user story describes a feature from an end-user's perspective. These features are very small, only further decomposable into design/development/testing tasks.

They can be grouped together under an Epic, which describes a feature of the application. Naturally, the feature described in a Epic is large.

Description Specification of the user, what they want, and why. This is commonly formatted like 'as [user], I want [a goal], so that [reasoning]'. It's highly preferable to use a persona as the user, instead of (re)defining users across stories or referring to 'user' generically.

For example, a user story for 'Sam' (a 21-year-old Instagram user) could look like 'As Sam, I want to login with my Facebook account, so that I don't need to remember another password'.

Acceptance Criteria A description of the expected functionality of the feature, covering happy and sad paths. These are also written from a user's perspective, containing what has happened, what is about to happen, and when should happen.

Using a behavioural format helps to maintain consistency, typically 'Given the user..., when..., then...'

For example, a happy path could look like 'Given that Sam clicks the 'Sign in' button, when he first opens the application, then he has the option to use Facebook to log in'

Designs Often they are exclusively for UI (sketches, wireframes, visual prototypes), but new features may also specify the technical approach (e.g., an ERD).