Ch3 Requirement Documentation
Ch3 Requirement Documentation
ENGINEERING
.
CHAPTER-3
Requirement Documentation
TABLE OF CONTENT:
Definition
Types of requirements
Product vs project requirements
Key players
Requirement development & management
Good practices for requirement engineering
DOCUMENTING THE REQUIREMENTS
The result of requirements development is a documented agreement among stakeholders about the product to be
built.
This addresses the purpose, structure, and contents of the SRS. We will describe the SRS as being a document, but
it doesn’t have to be in the form of a traditional word-processing document.
In fact, documents pose numerous limitations:
■ It’s difficult to store descriptive attributes along with the requirements.
■ Change management is clumsy.
■ It’s difficult to retain historical versions of the requirements.
■ It’s not easy to subset out a portion of requirements that are allocated to a particular iteration or keep track of
those that were once approved but then deferred or canceled.
■ It’s hard to trace requirements to other development artifacts.
■ Duplicating a requirement that logically fits in multiple places causes maintenance issues.
THE SOFTWARE REQUIREMENTS SPECIFICATION
• The software requirements specification goes by many names in various organizations, although organizations
do not use these terms in the same way. It is sometimes called a business requirements document (BRD),
functional specification, product specification, system specification, or simply requirements document.
• This addresses the purpose, structure, and contents of the SRS. We will describe the SRS as being a document,
but it doesn’t have to be in the form of a traditional word-processing document.
• The SRS states the functions and capabilities that a software system must provide, its characteristics, and the
constraints that it must respect. It should describe as completely as necessary the system’s behaviors under
various conditions, as well as desired system qualities such as performance, security, and usability.
• The SRS is the basis for subsequent project planning, design, and coding, as well as the foundation for system
testing and user documentation.
CONTT….
It’s important to organize and write the SRS so that the diverse stakeholders can understand it. Keep the following
readability suggestions in mind:
■ Use an appropriate template to organize all the necessary information.
■ Label and style sections, subsections, and individual requirements consistently.
■ Create a table of contents to help readers find the information they need.
■ Number all figures and tables, give them captions, and refer to them by number.
■ If you are storing requirements in a document, define your word processor’s cross-reference facility rather than hard-
coded page or section numbers to refer to other locations within a document.
■ If you are using documents, define hyperlinks to let the reader jump to related sections in the SRS or in other files.
■ If you are storing requirements in a tool, use links to let the reader navigate to related information.
■ Include visual representations of information when possible to facilitate understanding.
■ Enlist a skilled editor to make sure the document is coherent and uses a consistent vocabulary and layout.
SOFTWARE REQUIREMENTS SPECIFICATION TEMPLATE
• Every software development organization should adopt one or more standard SRS templates for its projects.
Various SRS templates are available (for example: ISO/IEC/IEEE 2011). If the organization tackles various
kinds or sizes of projects, such as new, large system development as well as minor enhancements to existing
systems, adopt an SRS template for each major project class. Figure illustrates an SRS template that works well
for many types of projects.
• Sometimes a piece of information could logically be recorded in several template sections.
• Avoid duplicating information in multiple sections even if it could logically fit in more than one.
• Cross-references and hyperlinks can help readers find the information they need.
• When you create requirements documents, use effective version control practices and tools to make sure all
readers know which version they are reading. Include a revision history to provide a record of changes made in
the document, who made each change, when it was made, and the reason for it.
.
REQUIREMENTS SPECIFICATION ON AGILE PROJECTS
• Projects following agile development life cycles take a variety of approaches to specifying requirements that
differ from the method just described. Each user story is a statement of a user need or functionality that will be
valuable to the user or purchaser of the system. Teams might begin specification on agile projects by writing just
enough information for each user story so that the stakeholders have a general understanding of what the story is
about and can prioritize it relative to other stories. This allows the team to begin planning allocations of specific
stories to iterations.
• The agile team is not precluded from using other methods to represent requirements knowledge, such as analysis
models or a data dictionary. They should select whatever representation techniques are customary and
appropriate for their culture and project.
• It’s up to each project team to choose the most appropriate forms for specifying its software requirements.
Remember the overarching goal of requirements development: to accumulate a shared understanding of
requirements that is good enough to allow construction of the next portion of the product to proceed at an
acceptable level of risk.
WRITING EXCELLENT REQUIREMENTS
• The best requirements repository in the world is useless if it doesn’t contain high-quality information.
• It presents numerous guidelines for writing requirements, along with many examples of flawed requirements
and suggestions for improving them. These recommendations apply to the requirements that are created for any
project following any development life cycle.
• The requirements on each project need to judge the appropriate level of precision and detail for their
requirements, but there’s no substitute for clear communication.
1. CHARACTERISTICS OF REQUIREMENT STATEMENTS
• In an ideal world, every individual business, user, functional, and nonfunctional requirement would exhibit the
qualities described in the following sections.
• Complete: Each requirement must contain all the information necessary for the reader to understand it. In the
case of functional requirements, this means providing the information the developer needs to be able to
implement it correctly.
• Correct: Each requirement must accurately describe a capability that will meet some stakeholder’s need and
must clearly describe the functionality to be built. This might be a user who supplied the initial requirement, a
higher-level system requirement, a use case, a business rule, or another document. A low-level requirement that
conflicts with its parent is not correct. To assess the correctness of user requirements, user representatives or
their close surrogates should review them.
CONTT…
• Feasible : It must be possible to implement each requirement within the known capabilities and limitations of the
system and its operating environment, as well as within project constraints of time, budget, and staff. A developer
who participates during elicitation can provide a reality check on what can and cannot be done technically and
what can be done only at excessive cost or effort. If a requirement needs to be cut because it is not be feasible,
understand the impact on the project vision and scope.
• Necessary: Each requirement should describe a capability that provides stakeholders with the anticipated business
value, differentiates the product in the marketplace, or is required for conformance to an external standard, policy,
or regulation. Every requirement should originate from a source that has the authority to provide requirements.
• Prioritized: Prioritize business requirements according to which are most important to achieving the desired value.
Assign an implementation priority to each functional requirement, user requirement, use case flow, or feature to
indicate how essential it is to a particular product release. If all requirements are equally important, the project
manager doesn’t know how best to respond to schedule overruns, personnel losses, or new requirements that come
along.
CONTT…
• Unambiguous: Natural language is prone to two types of ambiguity. One type I can spot myself, when I can
think of more than one way to interpret a given requirement. The other type of ambiguity is harder to catch.
That’s when different people read the requirement and come up with different interpretations of it. The
requirement makes sense to each of them but means something different to each of them. Inspections are a
good way to spot ambiguities.
• Verifiable: Can a tester devise tests or other verification approaches to determine whether each requirement is
properly implemented? If a requirement isn’t verifiable, deciding whether it was correctly implemented
becomes a matter of opinion, not objective analysis. Requirements that are incomplete, inconsistent, infeasible,
or ambiguous are also unverifiable. Testers are good at examining requirements for verifiability.
2. CHARACTERISTICS OF REQUIREMENTS COLLECTIONS
It’s not enough to have excellent individual requirement statements. Sets of requirements that are grouped into a
baseline for a specific release or iteration should exhibit the characteristics described in the following sections,
whether they are recorded in an SRS document, a requirements management tool, a set of user stories and
acceptance tests, or any other form.
• Complete: No requirement or necessary information should be absent. There are always some assumed or
implied requirements, although they carry more risk than explicitly stated requirements. Missing requirements
are hard to spot because they aren’t there. Any specification that contains TBDs is incomplete.
• Consistent: Consistent requirements don’t conflict with other requirements of the same type or with higher-
level business, user, or system requirements. If you don’t resolve contradictions between requirements before
diving into construction, the developers will have to deal with them. It can be hard to spot inconsistencies
when related information is stored in different locations, such as in a vision and scope document and in a
requirements management tool.
CONTT…
• Modifiable : You can always rewrite a requirement, but you should maintain a history of changes made to each
requirement, especially after they are baselined. You also need to know about connections and dependencies
between requirements so you can find all the ones that must be changed together. Modifiability dictates that
each requirement be uniquely labeled and expressed separately from others so you can refer to it
unambiguously.
• Traceable: A traceable requirement can be linked both backward to its origin and forward to derived
requirements, design elements, code that implements it, and tests that verify its implementation. Note that you
don’t actually have to define all of these trace links for a requirement to have the properties that make it
traceable. Traceable requirements are uniquely labeled with persistent identifiers. They are written in a
structured, fine-grained way, not in long narrative paragraphs. Avoid combining multiple requirements
together into a single statement, because the different requirements might trace to different development
components.
MODELING THE REQUIREMENTS
• Business analysts might hope to find one technique that pulls everything together into a holistic depiction of a system’s requirements.
Unfortunately, there is no such all-encompassing diagram. In fact, if you could model the entire system in a single diagram, that diagram would
be just as unusable as a long list of requirements on its own. An early goal of structured systems analysis was to replace the classical functional
specification with diagrams and notations that are more formal than narrative text.
Visual requirements models described in this book include:
■ Data flow diagrams (DFDs)
■ Process flow diagrams such as swimlane diagrams
■ State-transition diagrams (STDs) and state tables
■ Dialog maps
■ Decision tables and decision trees
■ Event-response tables
■ Feature trees
■ Use case diagrams
■ Activity diagrams
■ Entity-relationship diagrams (ERDs)
1. SWIMLANE DIAGRAM
Swimlane diagrams provide a way to represent the steps involved in a business process or the operations of a proposed
software system. They are a variation of flowcharts, subdivided into visual subcomponents called lanes. The lanes can
represent different systems or actors that execute the steps in the process. Swimlane diagrams are most commonly used to
show business processes, workflows, or system and user interactions. They are similar to UML activity diagrams. Swimlane
diagrams are sometimes called cross-functional diagrams. Swimlane diagrams can show what happens inside the process
bubbles from DFDs. They help tie together the functional requirements that enable users to perform specific tasks.
Swimlane diagrams can contain additional shapes, but the most commonly used elements are:
■ Process steps, shown as rectangles.
■ Transitions between process steps, shown as arrows connecting pairs of rectangles.
■ Decisions, shown as diamonds with multiple branches leaving each diamond. The decision choices are shown as text
labels on each arrow leaving a diamond.
■ Swimlanes to subdivide the process, shown as horizontal or vertical lines on the page. The lanes are most commonly roles,
departments, or systems. They show who or what is executing the steps in a given lane.
PARTIAL SWIMLANE DIAGRAM FOR A PROCESS IN THE CHEMICAL TRACKING SYSTEM.
2. DIALOG MAP
• The dialog map represents a user interface design at a high level of abstraction. It shows the dialog elements in
the system and the navigation links among them, but it doesn’t show the detailed screen designs. A user
interface can be regarded as a series of state changes. Only one dialog element (such as a menu, workspace,
dialog box, line prompt, or touch screen display) is available at any given time for user input. The user can
navigate to certain other dialog elements based on the action he takes at the active input location. The number
of possible navigation pathways can be large in a complex system, but the number is finite and the options are
usually known. A dialog map is really just a user interface modeled in the form of a state-transition diagram.
• Dialog maps look a bit like flowcharts, but they serve a different purpose. A flowchart explicitly shows the
processing steps and decision points, but not the user interface displays. In contrast, the dialog map does not
show the processing that takes place along the transition lines that connect one dialog element to another.
DIALOG MAP FOR THE “REQUEST A CHEMICAL” USE
CASE
FROM THE CHEMICAL TRACKING SYSTEM.
■ Temporal event A temporal event is time-triggered, as when the computer’s clock reaches a specified time (say, to launch
an automatic data export operation at midnight) or when a preset duration has passed since a previous event (as in a system
that logs the temperature read by a sensor every 10 seconds).
DEFINING QUALITY REQUIREMENTS
• As with all requirements, it’s a good idea to record the origin of each quality requirement and the rationale
behind the stated quality goals if these are not obvious. The rationale is important in case questions arise
about the need for a specific goal or whether the cost is justifiable.
• External quality attributes: External quality attributes describe characteristics that are observed when the
software is executing. They profoundly influence the user experience and the user’s perception of system
quality. The external quality attributes are availability, installability, integrity, interoperability,
performance, reliability, robustness, safety, security, and usability.
• Internal quality attributes: Internal quality attributes are not directly observable during execution of the
software. They are properties that a developer or maintainer perceives while looking at the design or code
to modify it, reuse it, or move it to another platform. Internal attributes can indirectly affect the customer’s
perception of the product’s quality if it later proves difficult to add new functionality or if internal
inefficiencies result in performance degradation. They are efficiency, modifiability, portability, reusability,
scalability, and verifiability.
THANKS!