Introduction

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 struggle to navigate organisational complexity, political decision-making, and siloed systems.

Being on the receiving end of a poorly performing development team is upsetting, particularly if you’ve tried everything to fix the situation but low throughput and poor workmanship remain. The business pays the hidden price for this; the individuals least well-placed to know what’s going wrong. Unfortunately, these experiences are only too familiar.

If your software development team is struggling and it’s holding back your business, then you’ve come to the right place. We believe better software requirements can literally change the world. Developers thrive when they know what to do and feel good putting their technical skills to work. Read on for some practical advice that might just change your life.

Let us know if anything strikes a chord: info@bettersoftware.uk


Table of Contents

Why software development goes wrong
My software development is going wrong
Better software requirements
Gathering software requirements
Writing software requirements
Special considerations
Better Software UK
About Frank
Contact us


Why software development goes wrong

Software development works best when developers interact directly with users, hearing about their experiences with the software and discussing what should come next. Conversations replace the need for requirements, and ideas and concepts are quickly put together and pushed out the door. Developers confidently release to real users because high-quality processes guard against adverse effects. Feedback happens in near real-time; a simple comment, under-the-breath muttering or facial expression is often enough to gauge reception. It sounds like fantasy, but commercial software really was built like this circa year 2000, and still is in many startups and small companies.

This approach works because developers know multiple technologies and can work up and down the stack, delivering entire working features themselves. Developers create database tables and stored procedures, develop middle-tier code and author front-end interfaces (often not very good ones, I admit). They may have strengths in particular technologies, but what’s most important is delivering whole solutions. Additionally, these developers converse with real-life humans, sketch out rudimentary designs, and even test finished code, a far cry from most developers today.

Technical silos

Modern software development is very different from the early 2000’s. Technical complexity means developers specialise in one or two technologies or frameworks, teams are distributed globally, ‘product ownership’ and ‘user experience’ are entirely new functions, and DevOps sits outside the development team. I’m not against any of this, nor am I advocating a return to an earlier time; rather, I’m pointing out how things have changed in the software development industry.

The distance between the end user and software developer is the biggest indicator of whether your software product will delight users, or be a poor proxy of misunderstood needs. The further you stray from close collaboration between users and developers, the greater the likelihood of things going wrong, and the greater the need to manage the software development process carefully. Developers not sitting with actual users, or user advocates, break the close collaboration and direct feedback loop that avoids the need for formal software requirements and software specifications in the first place.

Large corporations develop software in ways that definitively break the link between users and developers, leaving a communication gap of monumental proportions. Users and developers no longer collaborate; sometimes, they have never even spoken to one another. Remote development teams, outsourced and located offshore in supplier ‘centres of excellence’ is standard practice. The user feedback loop is broken too, needing to traverse through layers of product owners, user researchers, designers and business analysts, before ending up in ticketing systems like Atlassian Jira and Azure DevOps.

By all means, bring users and developers closer together if you can. But when you can’t, you need software requirements. It’s far from perfect, and often requirements are only a poor approximation of close collaboration and direct feedback, but you need them to bridge the monumental communication gap that exists today. Software requirements are an undisputed fact of modern software development, particularly in large corporate and enterprise settings.

Poor product management

Someone needs to tell the developers what to do, otherwise certain chaos ensues. Good software developers can tolerate a measure of ambiguity in their work; many enjoy putting their skills to good use and resolving unknowns. What developers cannot do, however, is make decisions on behalf of a business that doesn’t know what it wants or navigate political environments and organisational complexity from behind their development IDE. Developers struggle to do this.

Someone, somewhere, needs to convert ideas and concepts into software requirements for the developers, but it’s hard to do well because you really need to understand the business problem you are trying to solve. Then, you must communicate effectively. Not knowing what to tell the developers isn’t an option, unless you want poorly built software, idle hands, or conversations and ideas that never become a reality. Each developer needs a prioritised work stack and sufficient work to do; large development teams with broad skill sets make this particularly tricky.

Occasionally, the exact thing to build is known but the software requirements lack detail, such as acceptance criteria, business rules, testing scenarios, and other important things. You’ll see developers becoming blocked in their work, needing conversations to iron out the details, and then waiting for system access and environments to be made available. Better software requirements, adequate time to review them as a team, and consideration for third-party dependencies are usually the solution.

High risk scenarios

New proposition and product development, bespoke and custom software development, integration of multiple backend systems, system rationalisation and retiring end-of-life technology, several suppliers, outsourced and offshore development, poor quality or inexperienced developers, absence of critical project roles (eg. requirements analyst, technical lead, quality assurance manager), operating in regulated environments, safety-critical applications, a prior history of failed projects and poor delivery.


My software development is going wrong

You’ll attend a product demo and be either thoroughly underwhelmed at the progress made or simply furious at the sloppiness you see, or you’ll lie awake at night worrying that you don’t know what is being delivered, and when, even approximately or on a prioritised basis. These are major indicators that something is wrong with your software development process.

Regularly cancelled product demos because of overrunning development. Infrequent production releases to actual users. Production releases that go wrong; unexpected outages, data corruption and spiralling bug counts. Unhappy users when they finally get new software versions. Frustrated developers working in a team with low morale and high staff attrition. These are other indicators to look out for.


Better software requirements

Developers need to know what to do and be able to make the right decisions. Some developers tolerate ambiguity better than others, however they still need a clear understanding of what to do. Experienced developers in small teams with good access to users require less prescriptive requirements; junior developers in remote teams building enterprise software require more.

The further developers are away from end users and business stakeholders, the greater their reliance on written communication. Developers who work without direct, personal user feedback are heavily dependent on written requirements as their primary source of guidance. It’s true, irrespective of whether you philosophically agree or not. Some folk believe modern agile practices remove the need for software requirements, but this couldn’t be further from the truth.

Software requirements describe what is needed and provide sufficient information for good technical decisions. Design and implementation details are left to the developers to figure out, as they know most about the codebase. Regular refinement sessions ensure stories are understood and work can proceed without unexpected blockers or ad-hoc conversations. Maximum developer productivity and happiness are assured.

Gathering software requirements

Software requirements aren’t necessarily known in advance, they aren’t located in the heads of the stakeholders, and they aren’t solicited in back-to-back Zoom meetings, nor are they lying in hallways waiting to be collected like eggs from a chicken coop 🐓. Equally, going around saying “Tell me what you want” is a pretty terrible approach and certainly won’t provide the answers needed or hoped for. You wouldn’t need to hire a business analyst if it really was this easy.

Requirements gathering isn’t a simple linear process, and unfortunately, it often can’t be planned and executed in a deterministic manner. Sure, you can schedule two weeks of stakeholder interviews on a project plan, and you will find out a heap of stuff, but you may not get the answers you need to build the kind of software the business demands, and users want. Interestingly, IT system builds often represent a deep, unmet organisational need and there is immense value in accurately clarifying and surfacing it.

Time with users is probably the single biggest factor in gathering good software requirements. Adequate time to develop a relationship, build trust, listen intently, ask questions and hear feedback. Adequate time to see how they work, understand the daily pressures of the environment they work in, and other tools they use. Adequate time allows you to understand the competitive landscape, the needs of the business and the opportunities to do better or differently. With a keen eye and an inquiring mind, you start to understand the real needs of the users and stakeholders, and with luck, make known a provisional roadmap of features to address them. Software requirements follow, a written hypothesis of actual user need, soon to be built and validated.

“Have you got the requirements yet?” is a well-intended but misguided question anxious stakeholders ask when faced with an urgent need to deliver some kind of system, unrealistic deadlines and the desire for progress. If only the requirements were complete, then the real work could commence, goes their thinking.

Quickly capturing enough of a backlog for the first three sprints demonstrates progress, aligns developers and allows work to commence. Everyone starts to feel better. The risk of rework and the ability to pivot is considered when compiling the initial backlog, given the high chance of this early work being off the mark. Importantly, commencing development secures the time and remit to commence the real work of understanding deeper organisational needs through immersion in day-to-day interactions with users and stakeholders over time.

Writing software requirements

Expecting developers to magic something from a vague idea or a one-sentence user story isn’t a particularly helpful approach. Technical staff are great at solving relatively well-bounded technical problems but dire at stepping into the customer’s shoes.

Unfortunately, many software requirements are just too vague and open to interpretation. Select a few requirements from your team to inspect. Are they clear and effective? Do they convey the outcome required? Please tell me what you find.

What’s usually missing is all the context. Here are some helpful things to consider including alongside each software requirement, mindful not to slip into ‘solution mode’ when doing so:

  • Background information
  • Acceptance criteria
  • Alternative scenarios
  • Business rules
  • Error handling
  • Illustrations, UI mockups and designs
  • Research data and user feedback
  • Related product features
  • Clear directions stating what technical approaches are acceptable
  • Assumptions, constraints
  • Anything else relevant

Performance attributes and non-functional requirements (eg. accessibility, interoperability, redundancy) should also be defined. It is usually best practice to document these centrally for an overall product or product sub-system, referencing them from individual requirements. Technical details such as API endpoints and message schemas should only be included if they are significant or enhance readability.

Read more: Painless Functional Specifications


Special considerations

Remote development

Developers struggle when the people who can answer questions are not readily accessible or available. Remote developers struggle more due to their lack of co-location and increased reliance on written communication. Difficulty getting answers in real-time, waiting on emails, and language barriers are all things a local development team would never face.

Collaborating effectively across time zones is possible, but shifting to asynchronous communication and mostly written forms of communication is required. Remote teams working similar hours to the local business can more readily act as an extension of the local workforce, whereas other offshore teams perform best when responsible for end-to-end work, avoiding part-finished work bouncing between distributed teams.

Regardless of the approach, the remote team must work with you rather than against you. Accommodate their needs as best as possible and avoid the temptation to impose local processes without assessing their suitability first. Meet up in real life, at least once, to put names to faces and start developing some human relationships.

Neurodiverse developers

‘Can’t you just collaborate for once’ said the frustrated manager, perhaps not an uncommon experience for the developer it was directed at. But maybe they really could not collaborate, at least not in the way expected of them. Noisy office space, unstructured meetings, verbal instructions, business jargon and lack of written documentation might have been factors at play.

Around 1 in 6 people working in technology are believed to be autistic, a much higher rate than the general population (Tony Atwood, 2022). Neurodivergent traits can be incredibly valuable for technology workers, hence the increased prevalence; however, these individuals see, hear and process the world differently, sometimes drastically so. ADHD and other conditions often co-exist, adding to an already complex situation. Difficulties can arise, both interpersonally and at work, such that autism is a recognised disability under UK law.

Professional understanding, diagnosis and access to support are relatively recent occurrences, not widespread but certainly more prevalent than they were 20 years ago. Many neurodivergent individuals have lived their entire adult life flying under the radar, undiagnosed, unsupported and coping as best they can. Can you really be sure your ‘difficult developer’ is wilfully acting this way? You can’t.

Certainty, structure and routine are everyday needs amongst neurodiverse individuals, coping mechanisms for high levels of hidden anxiety. By their very nature, software requirements reduce ambiguity and clarify what’s required. Good software requirements do this to a level sufficient for the developer to work without worry. A welcome relief for many individuals.

Read more: The lost years of a young software engineer

Agile transformations

Some organisations don’t want agile. They say they do, but shop floor behaviour indicates otherwise. Unless the CEO personally spearheaded agile ways of working; small, autonomous, cross-functional product teams who release software frequently and practice continuous improvement are aspirational at best.

Agile remains one small initiative in the product or technology department, ready to be overridden, deprioritised or ignored when something more important comes along. This is the reality of building software in large enterprises, particularly if they aren’t in the business of technology.

Developers find this incredibly confusing, particularly when an agile coach espouses individual empowerment and bottom-up transformation despite an organisation that acts otherwise. The internal conflict of trying to work one way versus being inadvertently prevented from doing so can cause irritability, tiredness, fatigue, burnout and poor mental health. High levels of staff sickness and turnover are good indicators of this.

Software requirements are the antidote to confusion, ambiguity and undue personalisation. Slice the requirements thin, call them user stories, practice story refinement, get a solid definition of ready, adopt a rigid Scrum cadence and ask the agile coach to protect your boundaries.


Better Software UK

We’ve never come across a struggling development team that didn’t also have a software requirements problem. When developers habitually don’t know what to do, or don’t have enough detail to do it properly, certain chaos ensues. Use cases, agile user stories, business requirements, product backlogs, requirements catalogues; the title doesn’t matter, but someone needs to produce it. You don’t have anyone taking care of the software requirements? That’s the first thing to address.

A compelling product vision for everyone to rally around is also required, something that will emerge from daily interactions with users and the business. Clear and effective software requirements and a realistic delivery schedule will also become clear. Resolving organisational complexity and navigating political decision-making, both necessary activities, will de-risk the critical path and clear the way for software development to proceed at pace. A desire for control at a fairly low level means we sweat the small stuff, so you don’t have to.

Better software requirements will get your developers quickly building the right thing, and ensure they continue doing so. Your developers will know exactly what to do and be well-supported when doing it. Our work is highly effective and we aim to leave your team much better off, now and in the longer term. Given our extensive background as hands-on software developers, you simply won’t find software requirements like ours anywhere else.

Who we help

Engineering managers, technical leads, consultancy account managers; anyone with a small to medium-sized software development team, who are building enterprise applications or integrating back office systems, often outsourced and offshored, that is struggling to meet expectations and who need to improve matters, quickly.

What to expect

Expect your developers to quickly start building the right thing, and continue doing so. Expect your developers to know exactly what to do and be well-supported when doing it. Expect well-defined and implementation-ready software requirements, something you may not have seen before. Expect your team to be much better off long after we leave.

When to hire us

Hire us when the success of your business depends on high-quality software development. Hire us when poor-quality workmanship and high levels of rework are the norm. Hire us when you can no longer tolerate broken features, slow delivery, and increasing technical debt. Hire us when the cost to your bottom line of doing nothing makes our rates look small. Hire us when you want a good night’s sleep.


About Frank

Frank Ray

I’m Frank, a former Microsoft C# .Net software developer and owner of Better Software UK, a consultancy specialising in software requirements for agile development teams.

Remote, outsourced and offshore development is difficult to do well, and my time in enterprise software development teams, firstly as a hands-on developer and then as a business analyst, clearly showed me this.

I’ve written extensively about my workplace experiences and dedicated my professional life to improving software development. I discovered that I am autistic in my mid-40s and learned that it’s not uncommon for engineers. It’s also why I understand and communicate with other developers so well.


Contact us

We believe that better software requirements can literally change the world. Our promotional website was deleted in favour of trying to provide something genuinely useful above.

We’d love to hear from you: info@bettersoftware.uk