Requirements: The Life‑Breath of Software Development

When I was a teenager learning to scuba dive, my instructor emphasized the first and most crucial rule: "Breathe." At first glance, this seems like an unnecessary reminder—we breathe every day without thinking. However, the instinctive response to hold one's breath when the head is submerged can be surprisingly strong. In scuba diving, the danger of not breathing continuously and correctly cannot be overstated; it ensures that your body gets the required oxygen to function effectively under water.

Similarly, in the world of professional software development, our equivalent of “breathe” is “document requirements.” It seems like it should be obvious, but for various reasons that we will explore, we often forget or neglect this critical step, thereby depriving our process of the vital "oxygen" it needs to be effective. Failing to document requirements properly poses significant dangers, just as failing to breathe does in scuba diving.

To understand why documenting requirements is so essential, we will first look at how requirements are used throughout the development process and then examine some of the ways we frequently fall short.

Note: This article will not focus on the “how to” of documenting requirements. There are many methods and tools available, which are beyond the scope of this article.

Let's start by looking at how requirements are used in the software development process, by whom, and the dangers of missing or incorrect requirements.

1. Project Phase: Client Agreement 
   Consumers: Client and Project Owner/Business Analyst (BA)
   1. The requirements document the agreement between what will be created and what will be paid for
   2. Danger: completed project will not match expectations, at worst, resulting in dangerous or unusable software
2. Project Phase: Project Understanding and Estimation 
   Consumers: Developers, Project Manager (PJM), Product Manager (PDM)
   1. For developers, the requirements document the work to be estimated
   2. Danger: estimates will be off, project schedules compromised
3. Project Phase: Implementation 
   Consumers: Developers
   1. For developers, requirements serve as precise instructions detailing the work to be completed. Given their tendency to interpret tasks very literally, developers typically execute exactly what the requirements specify, omitting anything that is not explicitly included.
   2. Danger: incorrect or incomplete software may be developed, potentially with flawed design or architecture, making it more costly to rectify once the full set of requirements is identified.
4. Project Phase: Code Review 
   Consumers: Other Developers
   1. For code reviewers, the requirements detail the expected scope of change and standard of correctness as they verify implementation.
   2. Danger: bugs or missing features will not be identified
5. Project Phase: Testing at Various Levels 
   Consumers: QA, Client
   1. For testers, the requirements define the scope of changes and establish the standards of correctness as they identify defects.
   2. Danger: parts of the software will go untested, bugs potentially not caught
6. Project Phase: Post-Release (e.g., referencing original functionality and intentions) 
   Consumers: Anyone
   1. For all future team members, the requirements document outlines the original intended functionality of the software. This often continues to serve as the standard of correctness.
   2. Danger: future generations may have to reinvent the wheel, guessing the original intentions and being unable to accurately perform regression testing when changes are made.  

Requirements flow throughout the entire software development lifecycle (SDLC), like oxygen to our development process. At each step, there is danger if requirements are missing or incorrect, with an accompanying measurable cost, including redoing development and testing, delayed schedules, loss of public reputation or ruined relationship with clients.

Next, let’s take a look at some of the real examples of how we deprive our teams of this vital oxygen through poor or missing requirements.  

7. Too general, e.g. “Fix the UI styling to match design comps”
   1. While accurate, such statements are too vague and lack the necessary details for effective implementation. Moreover, they fail to provide QA with clear guidance on what needs to be tested. Instead, specify exactly which areas require attention through detailed written descriptions or annotated screenshots. This ensures clarity and precision, facilitating both development and quality assurance processes.
8. Lacking sufficient detail, e.g. “Show error message”  
   1. Either the developer is forced to chase down the exact message or uses one of their own choosing.
9. Missing steps
   1. The exact steps to reproduce a bug are vital to guide the developer to what needs fixing and to ensure the tester verifies the right sequence of steps. Missing details can result in testing the wrong behavior and getting a false positive, thinking the bug is fixed without ever testing it.
10. Requirement missing completely
    1. This is especially common when discussing requirement details; some specific aspect might be agreed upon in a meeting, email, or messaging, but never documented. Only a few parties know the actual requirements, not the entire list above.
11. Scattered, e.g. in ticket comments
    1. A common mistake is to have a discussion in the comment section of a ticket and consider that to be the documentation of the requirement. Not only are the actual acceptance criteria in the ticket out of sync with the decision, but this now requires all future users to sift through the comments to find new requirements. Once a decision is made, the formal requirements in the ticket should be updated or amended.  
12. Contradictory, e.g. comments versus acceptance criteria (AC), description versus AC
    1. A ticket will often describe the desired change in casual language then formally documented via requirements (or vice versa) but the two descriptions will not match. Similarly, comments on the ticket may contradict the requirements, creating confusion as to which represents the actual expected behavior.
13. Outsource to another document, e.g. design document, or visual design tool
    1. External documents can be invaluable for explaining detailed, complex requirements. For screen designs, they often provide the best way to convey design specifics, such as margins, fonts, shadows, and padding. However, the danger lies in the fact that these external sources may not be version-controlled. As a result, they can be updated after the referencing ticket has already been initiated, leading to inconsistencies and potential confusion.
14. Undocumented Work Added
    1. The final flaw occurs when developers address additional issues they notice while coding and incorporate extra work that is not documented in the ticket. Whether fixing a latent bug or making an improvement, this can unintentionally expand the project scope and introduce risks. For instance, the additional work might not undergo proper review or testing. It is crucial that all added work be thoroughly documented to ensure that all changes are appropriately processed. Refer to the flow above for the dangers associated with not documenting these changes.

This is just a small sample of the ways we can "forget to breathe" in the software development process. Whether due to forgetfulness, a rush for expediency, or a lack of understanding regarding the importance of documented requirements, we must remain vigilant to ensure clarity and precision. By adhering to the principle of "doing what we say and saying what we do," we can avoid the pitfalls that come with poor documentation. After all, even the best divers can only hold their breath for so long.