Documentation of quality requirements in agile software development

Context: Quality requirements (QRs) have a significant role in the success of software projects. In agile software development (ASD), where working software is valued over comprehensive documentation, QRs are often under-specified or not documented. Consequently, they may be handled improperly and result in degraded software quality and increased maintenance costs. Investigating the documentation of QRs in ASD, would provide evidence on existing practices, tools and aspects considered in ASD that other practitioners might utilize to improve documentation and management of QRs in ASD. Although there are some studies examining documentation in ASD, those that specifically investigate the documentation of QRs in depth are lacking. Method: we conducted a multiple case study by interviewing 15 practitioners of four ASD cases, to provide empirical evidence on documentation of QRs in ASD. We also run workshops with two of the cases, to identify important aspects that ASD practitioners consider when documenting QRs in requirements management repositories. Result and conclusions: ASD companies approach documentation of QRs to fit the needs of their context. They used tools, backlogs, iterative prototypes, and artifacts such as epic, and stories to document QRs, or utilized face-face communication without documenting QRs. We observed that documentation of QRs in ASD is affected by factors such as context (e.g. product domain, and size) and the experience of practitioners. Some tools used to document QRs also enhanced customer collaboration, enabling customers report and document QRs. Aspects such as levels of abstraction, the traceability of QRs, optimal details of information of QRs and verification and validation are deemed important when documenting QRs in ASD requirements management repositories.

💡 Research Summary

The paper investigates how quality requirements (QRs)—the non‑functional aspects that are critical for software success—are documented in agile software development (ASD) environments. While agile values working software over comprehensive documentation, this emphasis can lead to QRs being under‑specified, poorly recorded, or even omitted, which in turn may degrade product quality and increase maintenance costs. Existing literature has examined documentation practices in agile projects, but few studies have focused specifically on the depth and breadth of QR documentation. To fill this gap, the authors conducted a multiple‑case study complemented by workshops, gathering empirical evidence from 15 practitioners across four distinct ASD projects.

Research Design
The study selected four projects that varied in domain (enterprise resource planning, mobile application, embedded system, public‑sector web service), organization size (large enterprise, startup, SME, government agency), and team composition. Within each case, 3–5 participants—including product owners, scrum masters, developers, and QA engineers—were interviewed using a semi‑structured guide. The interview protocol covered (1) practitioners’ definitions of QR, (2) current documentation practices, (3) tools and repositories used, (4) factors influencing documentation decisions, and (5) perceived impact of documentation on project outcomes. In addition, two of the cases (the large ERP and the mobile startup) participated in facilitated workshops where participants collaboratively identified and prioritized the aspects they consider most important when recording QRs in requirements‑management repositories.

Key Findings – Documentation Strategies

1. Backlog‑Centric Recording – The majority of teams rely on mainstream backlog tools (Jira, Azure DevOps, Trello). QRs are entered as epics or large user stories, often enriched with custom fields, labels, or attached artefacts (e.g., performance test scripts). Some teams embed QR verification criteria directly into the Definition of Done, thereby linking QRs to automated testing pipelines.
2. Prototype‑Driven Capture – In UI‑heavy projects, teams capture QRs during sprint reviews or prototype demonstrations. The feedback is then transcribed into spreadsheets or wiki pages, preserving a trace from the prototype to the formal requirement. This approach balances rapid feedback with a degree of formalization.
3. Dedicated Requirements Repositories – A subset of organisations maintains separate requirement‑management systems (e.g., IBM DOORS, Jama, Confluence). Here QRs are documented in a specification‑style format, with traceability matrices that map each QR to design artefacts, code modules, and test cases.
4. Informal Communication – Small, highly collocated teams sometimes forgo explicit documentation, relying instead on meeting minutes, chat logs (Slack, Teams), or verbal agreements. While this reduces overhead, it depends heavily on team cohesion and shared understanding.

Key Findings – Influencing Factors
The authors distilled four primary categories that shape QR documentation practices:

• Contextual Factors – Product domain, organization size, team size, and the degree of customer involvement dictate the level of abstraction and detail required. Safety‑critical embedded systems demand precise, metric‑driven QRs, whereas consumer‑facing web services often accept higher‑level performance or usability statements.
• Practitioner Experience – Senior developers and product owners tend to integrate QRs into the development workflow (e.g., generating automated test cases from QR stories), whereas less experienced staff may create separate documents and rely on manual verification.
• Tool and Process Characteristics – Tools that enable direct customer input (e.g., Jira Service Desk portals) foster greater QR visibility and collaboration. Conversely, overly complex custom workflows can inhibit customer participation and lead to “documentation fatigue.”
• Intrinsic QR Attributes – The nature of the QR itself—its need for traceability, verification method, and granularity—guides the choice of documentation format. Security requirements, for instance, often require checklists and regulatory mapping, while performance requirements benefit from explicit metrics and associated test scenarios.

Implications for Practice
The study challenges the simplistic notion that agile automatically minimizes documentation. Instead, it reveals a nuanced landscape where teams deliberately tailor QR documentation to fit their specific context, balancing agility with the need for clarity, traceability, and verification. Effective QR documentation was found to (a) enhance customer‑developer alignment, (b) improve the efficiency of quality‑assurance activities, and (c) reduce downstream defects and maintenance effort. The workshops highlighted an “optimal detail” sweet spot: enough information to guide implementation and testing without inflating the documentation burden.

Conclusions and Future Work
The authors conclude that ASD teams should adopt a context‑aware documentation strategy for QRs, selecting tools and processes that align with domain constraints, team expertise, and customer collaboration goals. They recommend organizations conduct internal assessments to identify which QR attributes are most critical for their products and to configure their requirement‑management repositories accordingly. For future research, the paper suggests exploring automated traceability solutions (e.g., AI‑driven linking of QRs to code), longitudinal studies on the impact of QR documentation on product quality across multiple releases, and comparative analyses of QR documentation practices in emerging domains such as AI‑enabled systems and edge computing.