Software Requirements at the Prime[r]

A general understanding of a generally recognized and generally accepted foundation, loosely coupled with the corresponding SWEBOK V4 Knowledge Area (KA), which is still undergoing Public Review[1], along with some of my own Tourette twists disguised as a lexicon of liberties to give it a bit of just enough flair of neurotic diversity.

“But... to destroy Primus... is to destroy Cybertron!” - Megatron

“Thus will begin a new age - the age of chaos!” - Unicron

An emerging science of computational aesthetics

Software requirements are all about the communicative expression of the needs, constraints, and necessary activities to develop and maintain a software product in tandem with the project that enacts it.

Those things are located in the so-called application domain, or problem domain, but their communicative expression tends to be sucked into describing wished-for solutions patterned after the prevailing familiarity with ones already built, which are rather uncannily specific to other, even if similar, problem domains.

And that’s what one usually finds in the software requirements documentation: descriptions of a solution domain.

Software requirements are typically blamed for the unwelcoming increase in costs, delays and defects - its main utterances leading to design decisions, which are then pushed to code and test gone awry in exponential cascades of correcting rework.

The main issue revolves around the fact that human communicative expression always carries both incompleteness and ambiguity, the first mostly being revealed too few and too late, the second too many and too soon, permeating as much the initial development as through long-term maintenance.

What the code is intended to do then becomes the thing that baffles everyone and the place from where the bugs come, manifesting themselves as differences between what the software is intended to do and what it seems to be doing.

So, capturing and communicating such godly intent over the software’s service life isn’t just an upfront effort but rather a once-started never-ending ordeal to be tailored to the organisation and project context, by systematically handling its traversing through software architecture, design, construction, testing, and maintenance.

Requirements must therefore focus on the “what” and the “how” such work can and should be done, while delegating “when” it’s done to the project’s life cycle adopted approach.

Under a predictive, or “waterfolly” life cycle approach, requirements work appears as a front-end activity, expected to be substantially complete before any architecture, design and construction work ensues.

Under an iterative, “sensebaking” life cycle approach, an initial, inception phase is further tuned by one or more following elaboration phases.

In an Agile, “surprise-surprise” life cycle, requirements work is done incrementally, on the fly, on par with each software artefact’s construction.

Yet, the software intent communicated by the requirements work should be determined by the constructed software alone, irrespective of the life cycle employed, particularly to downstream software maintainers as those should remain happily oblivious to the life cycle used in earlier development.

Here’s to the fundamentals of a nervous breakup

A software requirement is a property to be exhibited by a computational ghost in connection with the environment in which it will appear operating.

Language being the raw material of description, software programs are descriptions in an assortment of funny, truncated languages, translated from specifications in natural but contrived language, which were translated from natural language descriptions of solutions to identified problems; the aforementioned requirements.

Software requirements are so rich as to be divided into categories. At the highest level, we have the categories of the software product requirements and the software project requirements.

The software project requirements, also called process requirements are most relevant to how the project is managed, accounting for cost, schedule, staffing, and the more than fifty ways to ruin a perfect software product, so we’ll leave it at that here.

Software product requirements are further decomposed into functional and non-functional requirements, lately also fashionable as behavioural and structural requirements, which can be as mutually reinforcing as self-defeating.

Typically, software behaviour determines its structure, following the canonical design principle of form follows function, in which the beauty of design results from the purity of function.[2]

Yet, software structure can also determine behavioural capabilities and boundaries, as per the axiom “If it flies, it spies.” by the Birds Aren’t Real movement.[3]

Non-functional requirements relate to the operation of the software in a finite-resource computational environment, and can still be further divided into technology constraints and quality of service constraints.

Technology constraints tend to intertwine with project management-related process requirements, constraining the use of certain software infrastructure – programming languages, databases, software stacks; remember Conway’s law[4] – or even particular programming techniques such as, for example, prohibiting the use of memory pointers, or mandating the use of programming languages with automatic garbage collection of program memory.

Quality of service constraints are requirements meant to specify acceptable performance levels such as response time, throughput, availability and scalability. And security, yes.

Childbearing and parenting activities

Requirements development is about reaching an agreement on what software is to be built, with plenty of gold plating, and requirements management is about maintaining that agreement over time, with plenty of reality checks.

To slay the dragon of incompleteness, requirements development begins with elicitation, also known as requirements capture, discovery or acquisition. It can be thought of as a primordial hunter-gathering activity, with its practitioners wearing thongs and only needing a saddlebag and a slingshot, or pencil and paper.

The stakeholder – who on occasion might be holding a stick – is where the raw, wild requirement lies, and it can be any person or group actively involved, affected, and influential to the project’s outcome.

It may be useful to segment the groups of stakeholders – of which some are even very well organised – into distinct classes in a Marxist twist by performing proper stakeholder analysis to allow steering through unavoidable negotiation and conflict resolution.

Some requirements don’t come from identifiable stakeholders; they’re more like environmental affordances, such as other interfacing software systems, or even the larger business context.

Such requirements come from within the territory where the software is to be generated, a sociotechnical system, which is a big ball of fur representing both natural and artificial elements as organizations of humans and machines.[5]

In a broader, much more entropic, dissipating sense, a system is an entity that manipulates one or more signals to accomplish a function, thereby yielding new signals[6] up to the point that, to those within a system, the outside reality tends to pale and disappear.[7]

Besides pencil and paper, requirements development practitioners also employ a variety of techniques to obtain requirements from stakeholders, like interrogation, meetings, a copious and diverse set of facilitation workshops, exploratory prototyping, and user story mapping, which is essential to learn that the word “requirements” actually means “shut up” and that stories aren’t the requirements.[8]

Next, to make sense of the collected dragon’s entrails, taking into account the ambiguity involved in an imaginary being’s anatomy, further investigation under the guise of requirements analysis will be forthcoming to distinguish what’s edible from what will drive people to the loo in droves.

Candidate requirements will need to be unequivocal, very desirable, and acceptable to all stakeholders. Other wishful attributes are completeness, particularly on what’s in and on what’s not in - but in after all, and consistently non-conflicting. Finally, they must be doable.

Once conflicting requirements are identified a resolution must be negotiated among the stakeholders and the resulting decisions should be traced, especially if related to the balancing of what’s stated for the software product to contemplate and what can effectively be accomplished under, among others, the proverbial project-level constraints such as cost and schedule.

Software requirements can then be translated into an intermediate, contrived, and peculiar language called requirements specification, in an attempt to enhance the chances of them both being better communicated and remembered, i.e., documented. This may be a hard-to-swallow tough one, but the specification format tends to be instrumental in ascertaining requirements testability, more reliable effort estimates, and tracing under proper configuration management.

Some organisations do it, some do not. It can be seen as much as an unnecessary overhead as dearly missed when facing the need to recover some of the requirements to assess the impact of proposed changes.

This also goes hand in hand with the choice between unstructured and structured natural language, in which such specifications can be expressed.

A typical example of unstructured natural language is business rules, sentences that define or constrain some aspect of the structure or behaviour of the process to be automated through software.

Yes, there was a time when it was hoped an entire business domain could be reducible to a set of machine-executable business rules.[9]

Yet, using software to prevent a student from registering for next semester’s courses if there remain any unpaid tuition fees, some logic would have to be applied, a kind of predicate logic at least.

Hence, structured natural language requirements specifications might advance the goal of precision and conciseness by imposing clarifying constraints on their expression.

One common approach is the actor-action format, where something happens that nudges the actor to act, followed by the action performed by the actor under some optional condition or qualification.

Use case specification templates are another good example, where one also has a triggering event that carries a parameter payload requiring something to happen, in exchange for guaranteeing something else will happen too while accounting for a main course of action, alternative routes, and even exceptions.

There’s also the user story format, which is very fashionable, particularly if you want to see BDD in action[10]: “As a <role> I want <desire> so that <rejoice>”. BDD stands for Behaviour Driven Development, amounting to the identification of a set of “scenarios” in the form of: “Given <some context> [and <possibly more context>], when <stimulus> then <outcome> [and <possibly more outcomes>].”

These are all variations on the same theme, it seems, all paying homage to the famous Bertrand Russell’s adage, that writing can be either readable or precise, but not at the same time.

Now to acceptance criteria-based requirements specification, from what is broadly known as the Test Driven Development (TDD) approach, the main tenet is that tests precede the construction of software. It starts with the selection of a tale about something that does something - a unit of functionality - followed by agreement on the set of tests that must be passed to show that something was done to something correctly. We’re either dealing with something which doesn’t exist yet or has a faulty existence from doing what it’s doing, mandating the creation or modification of production code to make it pass the tests; and on to select the next unit of functionality.

Another fancied approach to dissecting the imaginary anatomy of software beings is the use of models, as in model-based requirements specifications. Much like the blueprints used in building construction, modelling languages such as the Unified Modelling Language (UML) can facilitate precise and concise requirements.

As with economics, models allow both the exploration of phenomena within the model, as well as the real world the model is intended to represent.[11]

George Box and all, these models tend to carry a sort of double bind[12], immediately falling into two rubbing categories, one for specifying the structure and the other for behaviour, bearing on that tiresome recurring pattern of incompleteness and ambiguity.

Structural models describe a rather static organization of parts, as if of a sleeping ghost, through logical class models, conceptual data models, and logical data models such as entity-relationship (ER) models.

Behavioural models describe the genie when out of the box through use case modelling, interaction diagrams, state machinations, UML activity diagrams, and vintage dataflow modelling.

Models don’t usually appeal equally to all stakeholders, depending on the degree of formality they carry. Agile modelling is the least formal, conceived to help the understanding of important information, in which the effect of the communication matters more than the form.

More formal models strive to avoid critical reasoning errors, putting off most stakeholders. The aim is to prove correctness by construction, through logical correctness, conciseness and compactness, closing in on direct, mechanical translation into code, or at least a basis for deriving sound acceptance test cases.

This is where the issue of requirements validation comes in. It helps gain confidence that the developed requirements represent the stakeholders’ true needs as currently understood - and possibly documented. Reviews, simulations, and prototyping are the most common methods used, immediately after endless scholastic debates on a proper “definition of done”.

To maintain the above-mentioned agreement on what software one wants over time, some requirements management activities may be applicable, such as requirements scrubbing, to get rid of the dead wood that went out of scope or just isn’t worth the trouble anymore.

Depending on the Software Development Life Cycle (SDLC) one is stuck with, some measured degree of control over changes in software requirements will be necessary. Under plan-based life cycle approaches provision for change requests being acknowledged, analysed, accepted, rejected, deferred, notified and tracked must be accounted for. In contrast, requirements change management takes place implicitly in Agile life cycles, whereas a request is only accepted when prioritized high enough to make it into an iteration (a sprint), very much like in the Woody Allen sperm scene from the movie about everything you always wanted to know about sex but were afraid to ask.[13]

In sum, the software requirements process is one of many kinds, with an iterative nature that requires multiple passages through the subject matter. It usually falls prey to prioritization over a continuum of satisfaction and dissatisfaction that takes place under such stable volatility that can only be measured in volume and size, but is very amenable to quality standards and process improvements, as well as to the use of plenty of tools.

“We never do anything well

till we cease to think about the manner of doing it”

- William Hazlitt

---

[1] SWEBOK Evolution - IEEE-CS SWEBOK V4 Public Review (3rd Batch) – Comments Closing 9 January 2022 - https://www.computer.org/volunteering/boards-and-committees/professional-educational-activities/software-engineering-committee/swebok-evolution

[2] Lidwell, W., Holden, K., & Butler, J. (2003). Universal principles of design (1st ed.). Rockport.

[3] https://birdsarentreal.com/products/if-it-flies-tee

[4] “Looking into the VAX, West had imagined he saw a diagram of DEC’s corporate organization.” - Tracy Kidder (1981). The Soul of a New Machine. Avon Books.

[5] INCOSE (2023). SYSTEMS ENGINEERING HANDBOOK. John Wiley & Sons Ltd.

[6] Simon Haykin, Barry Van Veen (1999). Signals and Systems. John Wiley & Sons Inc.

[7] John Gall (2002). The Systems Bible. The General Systemantics Press.

[8] Jeff Patton (2014). User Story Mapping. O’Reilly Media.

[9] C. J. Date (2000). What Not How – The Business Rules Approach to Application Development. Addison Wesley.

[10] John Smart and Jan Molak (2023). BDD in Action, 2^nd Ed. Manning.

[11] Mary S. Morgan (2012). The World in the Model - How Economists Work and Think. Cambridge University Press.

[12] Gregory Bateson (2000). Steps to An Ecology of Mind. The University of Chicago Press.

[13] Agile sprint depiction. https://youtu.be/mGj1smf-_vc?si=-KGIqpPpD6K3l4DU