Generative AI on Enterprise Cloud with NiFi and Milvus
Writing effective requirements
1. Presented at a SA staff meeting at NCEN
by Liz Lavaveshkul
Source: TeleLogic
2. What is requirements management?
“The purpose of requirements
management is to establish a
common understanding between
the customer and the … project …
This agreement with the customer
is the basis for planning and
managing the … project.”
The Capability Maturity Model for Software (CMM) from the
Software Engineering Institute at Carnegie Mellon University.
www.sei.cmu.edu/cmm
3. Why is RM so important?
Approximately 60 – 70% of projects failures
result from poor requirements gathering,
analysis, and management.
-- Mela Group, March 2003
4. Why bother with Requirements?
• To show what results the users want
• To communicate and focus team members
on clear goals
• To tell decision-makers what is required
vs. desired
• To allow the design to be optimized
5. Why bother with Requirements?
• To supply confidence in the system
THOUGHOUT its development
• To check that the system and all its parts
do what is wanted
• To prevent over design or omitted needs
• To control development and outsourcing
6. Why do you need requirements
management?
• The status of the project is never clear until we find
we’ve missed project milestones
• We have very little formal development process
• The objectives always seem to change at the worst
times
• Change is very costly and time consuming for us
• We have difficulty communicating intent between
departments
• We end up over-engineering our solutions, which is
costly
Do any of the following statements seem familiar?
7. Why do you need requirements
management?
• We have trouble testing against original intent and stated
need
• We are never sure whether our tests are full and
complete
• Our test cycles are often too long and costly
• Our customers often include design in the requirements
• We have difficulty organizing requirements into smaller
manageable sets
8. Who should use a RM tool?
• Systems Engineers
demand functionality
• Highly advanced requirements
management and analysis
• Distributed users
demand collaboration
• Analyst/Architect
demand a common
language
• Reviewers demand
instant access from
any location
• Interested in central set of
requirements accessed
globally
• Need for multi-disciplines to
communicate more efficiently
• Not so advanced, mainly
interested in review
functionality
9. The Benefits of Requirements
Management
• Satisfaction
• Integration
• Testability
• Communication
• Visibility
• Change control
• Quality
• Optimization
• Compliance
10. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration
• Testability
• Communication
• Visibility
• Change control
• Quality
• Optimization
• Compliance
11. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration: the pieces work together
• Testability
• Communication
• Visibility
• Change control
• Quality
• Optimization
• Compliance
12. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration: the pieces work together
• Testability: know what to test the delivery against
• Communication
• Visibility
• Change control
• Quality
• Optimization
• Compliance
13. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration: the pieces work together
• Testability: know what to test the delivery against
• Communication: consistent ideas of what the
solution is for
• Visibility
• Change control
• Quality
• Optimization
• Compliance
14. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration: the pieces work together
• Testability: know what to test the delivery against
• Communication: consistent ideas of what the solution is for
• Visibility: managers can take a global
view
• Change control
• Quality
• Optimization
• Compliance
15. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration: the pieces work together
• Testability: know what to test the delivery against
• Communication: consistent ideas of what the solution is for
• Visibility: managers can take a global view
• Change control: the impact of change
can be assessed
• Quality
• Optimization
• Compliance
16. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration: the pieces work together
• Testability: know what to test the delivery against
• Communication: consistent ideas of what the solution is for
• Visibility: managers can take a global view
• Change control: the impact of change can be assessed
• Quality: we know what quality means for
the business
• Optimization
• Compliance
17. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration: the pieces work together
• Testability: know what to test the delivery against
• Communication: consistent ideas of what the solution is for
• Visibility: managers can take a global view
• Change control: the impact of change can be assessed
• Quality: we know what quality means for the business
• Optimization: we deliver only what is wanted
• Compliance: demonstrate compliance with regulatory authorities and SOX
18. The Benefits of Requirements
Management
• Satisfaction: real business needs met
• Integration: the pieces work together
• Testability: know what to test the delivery against
• Communication: consistent ideas of what the solution is for
• Visibility: managers can take a global view
• Change control: the impact of change can be assessed
• Quality: we know what quality means for the business
• Optimization: we deliver only what is wanted
• Compliance: demonstrate compliance with
regulatory authorities and SOX
19. Types of Requirements
• User Requirements – define
the results the users expect
from the system
• System Requirements –
define what the system must
do to satisfy the users
• Design Requirements –
define all of the components
necessary to achieve the
system requirements
“The homeowner shall hear an
alarm when smoke is
detected.”
“The alarm will produce a
sound between 125 – 155
dBA.”
“The alarm will be produced by
part # 123-45-678.”
20. Writing a requirement
• Uses complete sentences
• States subject and predicate
– Subject is a user type or the system under consideration
– Predicate is a condition, action, or intended result
• Consistent use of language
• Specifies:
– Desired goal or result (User requirement)
– Function (System requirement)
– Constraint (either)
• Contains a success criterion or other
measurable indication of the quality
21. Language
• Use consistent language, for example:
– “Shall,” “will,” or “must” are mandatory
– “Should” is optional, but omission must be justified
– “May” is desirable
• Use consistent terminology
– Define terms – use a Glossary
– Avoid using the same name for different things
– Avoid using different names for the same thing
22. Anatomy of a Good User Requirement
“The Internet user shall be able to access their
current account balance in less than 5 seconds.”
Defines a user type
Defines a positive end result
“To be” verb
Performance criteria
23. Anatomy of a Good User Requirement
• This requirement sentence identifies a specific
user and end result that is wanted within a
specified time.
“The Internet user shall be able to access their
current account balance in less than 5 seconds.”
Defines a user type “To be” verb
Defines a positive end result Performance criteria
The challenge is to seek out the user type, end result, and
success measure in every requirement you define.
24. Anatomy of a Good User Requirement
• It also defines the success in measurable
terms: “access … account balance in less
than 5 seconds.”
“The Internet user shall be able to access their
current account balance in less than 5 seconds.”
Defines a user type “To be” verb
Defines a positive end result Performance criteria
The challenge is to seek out the user type, end result, and
success measure in every requirement you define.
25. Characteristics of a Good Requirement
• Correct
• Complete
• Clear
• Consistent
• Verifiable
• Traceable
• Feasible
• Modular
• Design-Free
• Positive
26. Characteristics of a Good Requirement
• Correct
• Complete
• Clear
• Consistent
• Verifiable
Technically and legally possible
27. Characteristics of a Good Requirement
• Correct
• Complete
• Clear
• Consistent
• Verifiable
Technically and legally possible
Expresses a whole idea or statement
28. Characteristics of a Good Requirement
• Correct
• Complete
• Clear
• Consistent
• Verifiable
Technically and legally possible
Unambiguous and not confusing
Expresses a whole idea or statement
29. Characteristics of a Good Requirement
• Correct
• Complete
• Clear
• Consistent
• Verifiable
Technically and legally possible
Unambiguous and not confusing
Expresses a whole idea or statement
Not in conflict with other requirements
30. Characteristics of a Good Requirement
• Correct
• Complete
• Clear
• Consistent
• Verifiable
Technically and legally possible
Unambiguous and not confusing
Expresses a whole idea or statement
Not in conflict with other requirements
It can be determined that the system
meets the requirement
31. Characteristics of a Good Requirement
• Traceable
• Feasible
• Modular
• Design-Free
• Positive
Uniquely identified and can be tracked
32. Characteristics of a Good Requirement
• Traceable
• Feasible
• Modular
• Design-Free
• Positive
Uniquely identified and can be tracked
Can be accomplished within cost & schedule
33. Characteristics of a Good Requirement
• Traceable
• Feasible
• Modular
• Design-Free
• Positive
Uniquely identified and can be tracked
Can be changed without excessive impact
Can be accomplished within cost & schedule
34. Characteristics of a Good Requirement
• Traceable
• Feasible
• Modular
• Design-Free
• Positive
Uniquely identified and can be tracked
Can be changed without excessive impact
Can be accomplished within cost & schedule
Does not impose specific solution on design
(i.e., implementation free)
35. Characteristics of a Good Requirement
• Traceable
• Feasible
• Modular
• Design-Free
• Positive
Uniquely identified and can be tracked
Can be changed without excessive impact
Can be accomplished within cost & schedule
Does not impose specific solution on design
(i.e., implementation free)
Written in the affirmative, not the negative
36. Requirements Should be Correct
• The requirement should be technically and
legally achievable
– Have studies been completed?
– Does the technology exist?
– Will the implementation of the requirement stay within
existing legal guidelines?
37. Requirements Should be Correct
A correct requirement is one which does not try to
achieve some “pie in the sky” objective.
For example, the
requirement “The system
shall be 100% reliable” is
technically not achievable.
38. Requirements Should be Correct
A requirement may be technically achievable, but
not necessarily legally feasible because it may be
outside the framework of existing legal regulations.
For example, allowing the
user to access private
information online, without
the necessary security
checking, is technically
achievable, but is contrary to
current federal regulations.
39. Requirements Should be Complete
• Express a whole idea or statement
– Is the requirement standalone?
– Is the requirement dependent on preceding
requirements at that level of achievement?
– Is the requirement necessary for subsequent
requirements at that level of development?
40. Requirements Should be Complete
A complete requirement should not depend on
other requirements to be implemented. If a
requirement states “The radar system shall track
aircraft,” it leaves the reader asking “How many?
Inbound or outbound?”
41. Requirements Should be Complete
Also, beware of multiple requirements contained
within a single statement. For example, “The
system shall determine the number of users
online at all times and pass the number of users
to the system administrator who shall have the
ability to disconnect users from the Internet.”
42. Requirements Should be Complete
Instead, the statement can be broken down into
atomic statements:
Beware of multiple requirements contained within a single statement.
For example, “The system shall determine the number of users
online at all times and pass the number of users to the system
administrator who shall have the ability to disconnect users from
the Internet.”
“The system shall maintain a log of online users.”
“The system shall provide log information to the system
administrator.”
“The system shall allow the system administrator to
disconnect user(s) from the network.”
43. Requirements Should be Clear
• The requirement should be unambiguous
and not confusing
– Use words that are not confusing
– Use a commonly agreed set of terms
– The construct of the sentence should be standard
– Use definite, concrete terms
– Omit needless words
– Avoid language the target reader may not understand
– Do not overwrite
44. Requirements Should be Clear
When writing a requirement, always strive to
maintain clarity. An excellent reference is “The
Elements of Style” by Strunk and White.
For example, don’t “utilize” a function,
rather “use” a function.
45. Requirements Should be Clear
When you use the word “system,” do all the readers
have the same understanding of the word?
If you try to impress your readers with
arcane grammar only used in graduate-
level English classes, you will most likely
confuse and irritate them, as they will
have to reach for the dictionary too many
times.
46. Requirement Should be Consistent
• The requirement should not be in conflict
with other requirements
– Are there redundancies?
– Are the same terms used throughout?
– Are all requirements referencing the same dictionary?
– Requirements repeated in many sections can be
pulled into a common requirements set to avoid
duplication
47. Requirements Should be Verifiable
• Verification Methods:
– Testing
– Analysis
– Demonstration
– Inspection
48. Requirements Should be Verifiable
• It can be determined that the system
meets the requirement using one of the
standard verification methods:
• Testing: Usually the most
comprehensive of the verification
methods. This is also commonly referred
to as “white box” testing.
This method tests not only the output,
but also how the output is achieved,
considering the unique internal
deviations as a result of different states
and nodes.
49. Requirements Should be Verifiable
• Analysis: This method generally uses
mathematical algorithms
(expressed nowadays in computer
simulations) to ensure the
requirement is met.
50. Requirements Should be Verifiable
• Demonstration: also known as
“black box” testing, where the
system is given input, and the output
is compared against the expected
results.
51. Requirements Should be Verifiable
• Inspection: As the name implies,
this method checks or inspects the
system to ensure conformity to the
requirement.
52. Requirements Should be Verifiable
• You should always ask, “Is the
requirement testable?”
• When the requirement is implemented and
the system is built, you need to verify that
the system, indeed, does what is required
of it.
– To verify the system, people generally use
one of the four classic verification methods
mentioned previously. (Testing, Analysis,
Demonstration, and Inspection)
53. Requirements Should be Traceable
• The requirement should have a unique
identifier and traced to its origin.
– Ensures completeness
– Prevents “scope creep”
– It is a specific goal in any Requirements Management
process
– Allows quick impact assessment when requirements
change
54. Requirements Should be Traceable
• A primary aim of any requirements
management process is traceability of
requirements.
How much traceability?
100%!
55. Requirements Should be Traceable
• According to Standish Group, 52% of
required functionality is never included in
the finished system. Then, when system
testing commences, you discover the
missing functionality. You then have to not
only fix the system to accommodate the
missing functionality, but you have to test
all of the other requirements again to
ensure that the fixed requirement will not
break any existing functions (commonly
referred to as regression)
56. Requirements Should be Traceable
• When requirements change, as they
almost always do, the impact must be
accessed to ensure that the potential
change will still satisfy the parent
requirements and not adversely impact the
child requirements.
57. Requirements Should be Feasible
• The requirement should be written so as to
be achievable within cost and schedule
– Do you have the resources?
– Do you have the time?
– Do you have the right people?
58. Requirements Should be Feasible
A requirement may be technically achievable, but
way beyond the scope of current project
resources.
For example, you have a requirement that states,
“The system shall maintain a 99.9% mean time
between failures,” but the costs of achieving
99.9% reliability may be so exorbitant that the
other requirements may not be implemented due
to insufficient resources.
59. Requirements Should be Modular
• The requirement should have limited
cross-referencing interdependency.
– Group similar requirements together
– The use of a standardized outline structure helps
tremendously with achieving modularity.
60. Requirements Should be Modular
This allows the requirement to be changed
without excessive impact. For example,
the I.E.E.E. 12207 standard contains the
different outline templates for the various
types of requirements in a system, from
the Concept of Operations (CONOPS) to
the Software Test Plan (STP).
61. Requirements Should be Modular
• When you use these templates, you
achieve several goals:
– You start achieving modularity
– You are starting to standardize your process
62. Requirements Should be Design-Free
• The requirement should be
implementation-free
– Avoid design
– Describe what is required, not how it would be
implemented
– The requirement should be written with enough detail
to satisfy the level above
– The requirement should be written at a level of
abstraction to be design free for the next level below
63. Requirements Should be Design-Free
• During requirements development, we tend to want to
jump right into the design of the system
• Instead of trying to describe the desired functionality or
stakeholder wants, we tend rather to state how the
system will be implemented. Many times, this leads to
increased cost and complexity because the optimal
design space has now been restricted.
• For example, a system requirements document may
state: “The network shall use an ATM protocol.” This
constrains the design of the network to use ATM
technology, when another protocol may be the more cost
effective solution.
64. Requirements Should be Positive
• Requirements should be written in the
affirmative.
– Reduces the chances of having two requirements say
the same thing.
– Reduces the possibility of two requirements being
inconsistent — one stating something in the
affirmative and one in the negative but with different
conditions or numeric values
– Helps with the verification — it is much easier to test
to a positive statement where something observable
will happen as a result of a user action
65. Requirements Should be Positive
– A negative statement that a user action or
statement that something will not result in a
condition would be more difficult to test and
observe
– Less chance of misinterpretation, especially in
the case of double or multiple negatives
66. Requirements Should be Positive
For instance, instead of stating:
“No unsuccessful login attempts will go
unrecorded.”
Try rather:
“All unsuccessful login attempts shall be
recorded.”
68. Rate this Requirement
“The Order Entry system provides for quick,
user-friendly and efficient entry and
processing of all orders.”
Is this a good requirement? If not,
recommend an improvement.
69. Rate this Requirement
“Invoices, acknowledgements, and shipping
notices shall be automatically faxed during
the night, so customers can get them first
thing in the morning.”
Is this a good requirement? If not,
recommend an improvement.
70. Rate this Requirement
“The system OS shall be upgraded in one
whack.”
Is this a good requirement? If not,
recommend an improvement.
71. Rate this Requirement
“The ATM user shall be able to view the
current account balance after an update
within 5 seconds.”
Is this a good requirement? If not,
recommend an improvement.