Frank Ray

Software expert witness for IT and software development disputes.

Better Software Requirements

A handbook for software development teams and their managers.

Many developers don’t speak to users or collaborate with the business — instead, they take direction from email threads and poorly written tickets. Remote, outsourced and offshore developers know this only too well. Even with better access to people, these developers would face organisational complexity, political decision-making, and siloed systems.

This handbook is written for development teams and their managers who need to build software that delights the people who use it. It explains when software development works best, what happens when your team can’t work like that, and provides practical advice to address common pitfalls.

What Better Requirements Look Like

Most software requirements fail in the same way. They describe what the system should be, not what someone needs from it.

A typical bad requirement reads:

Before

"The system must be fast."

Rewritten so a developer can build it, a tester can verify it, and an offshore team can hand it back without ambiguity:

After

"On a standard work-laptop and the office VPN, the order-search screen returns the first ten results within 800 milliseconds for 95% of queries."

The first is a sentiment. The second is something the team can work from, and in an IT dispute, it is the difference between requirements that stand as evidence and those that do not. This handbook works through the patterns that get you from one to the other, across the full requirements lifecycle.

Contents

The book has two halves. The first five chapters are the requirements lifecycle, in order. The last four apply that lifecycle to the situations where it is hardest: agile teams, distributed and offshore teams, legacy replacements, and the technical debt that builds up along the way.

Part One — The Requirements Lifecycle

01 Introduction When software development works best, why it goes wrong, and what developers really need. 02 Gathering Requirements How to discover and capture what needs to be built without falling into common traps. 03 Writing Requirements What to include in functional and non-functional requirements, including context, acceptance criteria, and level of detail. 04 Reviewing Requirements How to develop requirements as a team through structured review sessions. 05 Implementing Requirements How developers work most effectively and what good requirements enable.

Part Two — Requirements in Practice

06 Requirements for Agile Teams Why agile teams need requirements — just different ones — and how Scrum and tailoring fit. 07 Remote, Offshore and Outsourced Teams Why distributed teams need more structure, not less, and how to make offshore work. 08 Replacing Legacy Systems How to discover requirements that were never written down, and rebuild without losing them. 09 Managing Technical Debt How shortcuts accumulate, what they really cost, and how to keep debt from quietly slowing the team down.

Appendices

A Functional vs Non-Functional Requirements How to tell the two kinds of requirement apart, with comparison tables and the boundary cases. B Non-Functional Requirements How to specify the quality attributes: performance, security, accessibility and all the rest.

Get the Book

Better Software Requirements on AmazonThis handbook is also available as a Kindle book on Amazon.

About the Author

I’m Frank Ray, a software engineer with over 20 years in enterprise development.

This handbook draws on those years inside enterprise teams: financial services systems, large platforms, and mixed onshore and offshore delivery. The patterns that recurred across those projects became the handbook, covering what makes requirements work in practice and what makes them quietly fail.

Those same years now inform my work as an independent software expert witness, where poorly written requirements are one of the most common threads running through failed software projects and the disputes that follow.