Next Mile and Space Cowboy have collaborated on a four-part series about requirements. You can read the first, second, and third parts at their respective links. Our final piece gives BAs the fundamental framework needed to construct useful software requirements for designers, developers, testers, and supporting stakeholders.

—

Attention! At ease. Listen up, BA.

Requirements are tasks. After all the elicitation, analysis, and documentation you undertake as a BA on a software project, you end with tasks others complete to defined parameters. Your end point is someone else’s starting point, and from here, that person will build their own checklist from all your “ands” and “if/thens” and execute against it.

As a BA, equipping those people—your comrades—for success, is your chief responsibility. They’re the troops, you’re their quartermaster. To do your job effectively, you need to know:

1. Your mission sequence
2. Requirements audiences and purposes
3. Requirements delivery theory
4. Your tradecraft: a flexible, parametric requirements template

We prime you with each below. Good hunting, BA!

We’ll assume you’re starting from a brand new software idea. As the BA, you’ve been brought in to assist an aggressive champion who needs additional firepower to advance their idea beyond a mere twinkle in their eye and into a describable, vettable concept.

1. Distill the vision into a concept

When discussing a new idea, most people need something to react to. Therefore, your work must help current and potential stakeholders (and detractors) imagine what your software will do. Your first mission is to translate an incomplete vision into a comprehensible concept. By doing that, you build the instrument that kickstarts others’ thinking, which you can then use to obtain their reactions and rationalizations.

Here are your first pass’s key elements:

1. Purpose and core features: the elevator pitch
   1. Primary user features

   2. Primary technical features

2. User interfaces containing said features: for most reviewers, this’ll be the meat of this document and the arena where most stakeholders will rumble
3. Technical needs: help emotional developers understand that you're onboard with their concerns by carving out space for their tasks
4. Development enablement needs: a.k.a resources/costs, use these ensure that everyone is aware what this’ll really take to execute

Keep your descriptions functional and write primarily from the user’s perspective. Use bulleted lists liberally and try not to exceed 1.5 pages. You’ll apply this instrument in the next phase.

2. Get reactions

Your second mission is to generate and capture reactions to your software concept. Select your stakeholder targets, then combine your newly-defined concept with your elicitation skills to extract the desires, anxieties, edge cases, yawning gaps, and other issues that threaten the feasibility of your application:

• Priority?
• Conflict?
• Completeness?
• Implementable?
• Budget?
• Timeline?
• Consumer insight? (mockups + CI methods)
• Everybody onboard?
• Taking this action will make me feel bad because…
• Taking this action will make me feel good because…

You’ve got to make people feel understood or your project will be covertly blocked well after it’s approved.

3. Seek approval or denial

Less your job and more your champion’s, you’ll still play a role in persuading approvers. A few tips to help you through your third mission:

• Stay mostly neutral, arguing from the data you collected (both pros and cons)
• Argue from users’ point of view
• Temper your champion if needed—it’s very possible they’ll argue in favor of a bad decision
• Balance hard-charging detractors similarly—champions aren’t the only ones who make bad arguments

Most businesses today will have at least one core value focused on avoiding inertia, so there’s a natural premium placed on action. Politically, it can be costly to argue against building a new thing. Sometimes though, you’ll stumble across a truly terrible idea. When that happens, argue from the data and hope it sinks in, or at least produces a decision.

4. Write the requirements

If you’ve got the green light, it’s go-time for your fourth mission: writing the actual requirements. Much more on this in subsequent sections. As we wrote previously, keep audiences involved as you develop your approach. They can’t tell you how to do your job, but they can tell you how they do theirs. Begin with this in mind.

5. Requirements management

Requirements management is the process of managing changing requirements during the requirements engineering process and system development. This is your maintenance task—nobody ever writes a single draft and gets everything right because:

• Requirements are inevitably incomplete and inconsistent
• New requirements emerge during the process as business needs change, and participants form a better understanding of the system
• Different viewpoints have different requirements which may contradict

Your requirements management work will be ongoing, likely going beyond your team's 1.0 launch deep into incremental iteration and product operation.

In many places, design requirements, engineering requirements, and testing requirements say three different things. When they contradict, nothing's true, and any requirements simply document useless information.

Controlling contradiction is an exercise in managing and deconflicting requirements audiences and purposes.

Requirements audiences

Most requirements documents have matrixed audiences and hence even-more-matrixed audience needs:

• User requirements
  • Client managers

  • System end-users

  • Client engineers

  • Contractor managers

  • System architects

• System requirements
  • System end-users

  • Client engineers

  • System architects

  • Software developers

• Specification documents
  • Client engineers (maybe)

  • System architects

  • Software developers

We point this out to highlight that your requirements output will never be perfect for everyone every time. Typically, the best you can do as a BA is:

• List your known audiences
• Understand the perspective and concerns of each
• Prioritize that list for a given requirement (and document)
• Cycle through that list when writing a requirement
• Ensure you’ve offered each audience something meaty

Run that sequence like a program or pre-flight checklist regularly to spot gaps and conflicts before they metastasize. When issues crop up, update this checklist accordingly.

Requirements purposes

To complicate things further, requirements are every bit as diverse as their audiences. The most common requirements types BAs have to write include:

• Functional user requirements describe services the system should provide, how the system should react to user input, and how the system should behave in specific situations. These are often high-level: “After viewing the splash screen, users will be asked for their login credentials.”
• Functional system requirements describe the system services in detail. For example, “The user shall be able to search either all of the available databases or select a subset from it.” or “Every order shall be allocated a unique identifier (ORDER_ID)”.
• Nonfunctional requirements are a broad category describing a. organizational parameters that apply to the software like known constraints, standards, methods, processes, and regulations, b. technical elements like the application’s security, availability, and speed, and c. contextual requirements arising from external factors like interoperability requirements or physical environment limitations.
• Performance requirements define a level of quality, the system’s business- and customer-acceptable response time, availability, scalability, resource utilization, and throughput. Performance requirements are primarily non-functional, but often mix in functional elements.
• Domain requirements state otherwise-implicit of the software’s operation in a given domain. “As a Federal government-run application, searches of the XYZ category are expressly forbidden.”
• System requirements address more than just a single application, defining the interaction between multiple technologies to achieve a singular user experience.
• Application interface specifications define an application’s interface types, interface layers, interface behaviors, the exchanged data structures, and any contract parameters.
• User interface specifications guide design effort on complex systems, defining specifics like which element should be seen where, that element's specific function, or the user’s pathway to and from said function.

Any software project could necessitate any or all of these, varying in form and emphasis. This isn’t an exhaustive list by any means, either. Start with your assessment of audiences and needs and evolve from there.

All practices extend from a core principle. With requirements, that principle is drilling down to help your readers focus on what’s important and why. To help people zero in, your documentation should illustrate:

1. The hierarchy
   1. The requirement’s place in the hierarchy
      1. The requirement’s relevant context
         1. That requirement’s specifics

Caution: Additions beyond your initial drill down can just as easily add confusion as they can clarification.

Use the tools available to help your reader get what they need quickly without wading through irrelevant details.

• Where appropriate, use expand/collapse containers that hide information until expanded by the reader.
• Include a hyperlinked table of contents at the top of the document.
• Use terminology that the reader is familiar with, and do so consistently.
• Complement text with bite-sized illustrations where appropriate (e.g., sequence diagrams, state diagrams, decision trees, matrices).
• Consider extracting long sections into their own page and providing a link to it.

Fundamentals first

At their lightest, requirements statements hit with a 1-2 punch:

1. A user story lays down valuable context right away
2. Acceptance criteria draws box around the engineer's problem

To reiterate, deliver the what and why and make a fence around the problem by defining a successful solution. This creates an engineering space, encourages developers to engage with the challenge, and causes participants to make their own checklists (a.k.a. thinking/engineering) instead of working mindlessly. This method also allows you to feed requirements to designers.

If you’ve achieved the above, you’ve hit the target. The rest is, technically, flourish.

Flourish second

Some flourish can be extremely useful, even necessary. Beyond the basics, your requirements might (and probably should) communicate these and more:

• Navigation: __where does this fit into the experience?
• Performance: what does "good" look like/mean?
• Computational specifics like "system should", data in/out/processing, etc
• Context empathy/why/expected value
• Forecast future considerations
• Enforce error handling preferencesDependencies called out to help ensure there aren’t missing pieces

The critical point is that these details aren’t useful if you’ve failed to deliver the fundamental user story/acceptance criteria 1-2 combo first. In our experience, if you find yourself spinning on this kind of information, you’ve either nailed the fundamentals almost autonomically, or you’ve missed them entirely. In that case, take a moment to check yourself and your work.

If you’re looking for a concrete starting point, we use this skeleton to create our project-specific requirement outline prior to building content. Sections include:

• Ticket parameters
• Requirement overview
• Work estimate
• Interface needs
• Logic, data, and integration needs
• Test needs
• Future considerations
• Other considerations

This outline focuses on a requirement, not a complete requirements document. Take only what you need, throw out everything you don’t. Fit the information into a format that makes sense to your audience.

Ticket parameters

NAME Descriptive, unique name that's searchable/minimizes repeat words (What would developers find useful? Perhaps "RECIPES-SAVEARECIPE")

CREATE DATE

REVISION DATE

ID Unique requirement ID +Jira link (assigned by system, "PROJ-TICKETID")

TYPE What does this requirement describe? A service, interface, data, business logic, etc.

PLATFORM if applicable, iOS, .NET

STATUS if applicable (property of Jira ticket)

PRIORITY if applicable (part of backlog usually)

DEPENDENCIES identify relevant prerequisites/dependencies, hit other tickets OR call out business/design/etc.

RESOURCES available resources, e.g. deep links to interactive prototypes, other production files, API documentation, etc. (Move this? Appendix? Keep here?)

Requirement overview

FLYBY Super short description separated from below, probably looks like a quote. Describe from the user's perspective. "User should see X, X should do Y, user should see/get/feel Z." (second level "X.X")

PURPOSE Justification for feature, whether user, market, dev efficiency (why)

ORIENTATION Content navigation: "a new part of the Map screen" (where does this fit into the application?)

QUESTIONS Open questions that must be resolved before work can begin

USERVALUE Expected value for audience

USECONTEXT Expected context of use (where/when/how)

REQUESTER The person who put the requirement in place and can help to negotiate obstacles

Estimate

CAPABILITY Required, might be multiple

BUILDER Who's going to do the work?

STORYPOINTS Estimated, if applicable

HOURS Estimated as a range

SPEND Hours ranged multiplied by average external agency rate (~$150/hr) or other determined rate

DURATION Using the estimate, how long will this take?

CONSEQUENCES What happens if we build this? CSAT up/down? Tech debt incurred/resolved? Efficiency gained/lost?

Interface needs

SCENARIO Narrate intended experience scenario, narrated from the user's perspective. (Borrow/merge from overview?)

CONDITIONS Prerequisite conditions: applies to/prerequisites (when?)

DEFINITIONS Jargon definitions, if any (e.g. "Shrapnel", "AKI")

INTELLIGENCE How did this test in any prior CI investigation?

KPI Does prior research give an idea of what good looks like?

STATE What state are the user, device, and anything else expected to be in?

SEE Describe visible elements. "User should see X, Y, Z."

ACT Highlight actionable elements. "User can act on A, Q, D."

INPUT Describe user input types per element.

RESPONSE Describe interface response per element

RESULT Describe ultimate result from interaction

SETUP Should the user set up for a next action? What is it?

STATECHANGE What contextual state changes occur? Which matter? How should they behave?

FAILUP The design state enables options, e.g. reconnect, authorization, etc.

FAILDOWN The design state disables options, e.g. disconnection event

INDICATORS Describe other UI changes like status indicators and available options

UIACCEPTANCE Key acceptance criteria that must occur

UIREJECTION Key acceptance criteria (rejection criteria) shouldn't happen

Logic, data, and integration needs

CONSTRAINTS Describe relevant data, logic, and user input prerequisites

DATAFLOW

INPUTS

SOURCES

OUTPUTS

DESTINATIONS

TECHSTATES Feature preconditions, postconditions, side effects

DEVACCEPTANCE Key acceptance criteria that must occur

ERRORS Describe error handling preferences like state management, verbosity, logging, etc. (As an acceptance criteria. "In an error condition, I should see X.")

PERFORMANCE Mandatory, desirable, an bonus-level performance requirements for this specific interaction if blanket requirements don't apply.

DEVREJECTION Key acceptance criteria (rejection criteria) shouldn't happen

ANALYTICS What data points do we want to capture? Send to where?

Test needs

UIACCEPTANCE Import from interface.

DEVACCEPTANCE Import—lean on acceptance criteria.

UIREJECTION import from interface.

DEVREJECTION Import from logic/data/integration.

DONE Further definition of done if needed.

UAT/BAT Instructions on further user/business acceptance testing, assuming an approval workflow.

Future considerations

ROADMAP If the roadmap contains a future element that might impact this feature, identify it here.

PREPARATION Describe recommended preparatory action.

Other considerations

LEGAL Considerations

CONTENT Considerations such as written copy and images needed to bring the requirement to life.

---

Space Cowboy and Next Mile make requirements effective. Reach out to us for software and hardware requirements that make your project more efficient.