1. Mixing Requirements, Modeling, and Code (Java)Finally software requirements that aren't lip service!
Daniel Brookshier, Chief ArchitectNo Magic Inc.
DanielB@NoMagic.com

2. Requirements of the Presentation
Learn why formal requirements are still important
Learn how to model requirements with SysML
Learn how requirements are much better via SysML
Learn how requirements via a tool is compatible with Agile
See how we can better manage requirements with standard UML tools
Manage unit tests and Java code via requirement models
3. Requirements Suck!!!
Requirements failure!
Written by the wrong people
Poorly written
Verbose and confusing or terse ambiguous
Written and forgotten
Overdone or underdone
4. The plan is nothing; the planning is everything.Dwight Eisenhower
5. Cant live with them, cant live without them!
Scopes work
Discovers goals
Sharable viewpoint
Trace to design
Traced to work
Trace to tests
Find related capability
Ensures completeness
Links iterations
Aids Re-use
Avoids the problems of dementia
6. Waterfall or Agile Requirements?
Waterfowl
Exhaustive up front
Set them in concrete!
Forget!
Agile
Create top requirements
Focus on functional
Focus on performance
Clear language
Detail/Refine/change requirements on each iteration
Forget
Repeat
7. 8. Modeling Requirements in UMLSysML Requirements 101
9. What is SysML?
SysML = Systems Modeling Language
Extension of UML
Oriented at modeling systems and system of systems
Various levels of detail
More rigor than UML
Requirements are part of SysML
Designed for use in models
Extensible
Model abstract to detailed requirements
Derive requirements from other requirements
Reuse requirements from other models
Traceability to design, tests, and other information
10. What is SysML really?Semantic Tagging!
The problem is too many words
The solution is to tag words and link to context
SysML uses tags on UML to create semantics of Requirements
11. Whats The Goal of SysML Requirements?
Requirement Modeling:
Atomic Requirements
Reusable
Flexible linkages
Where they come from?
How are they related?
What satisfies?
Whatverifies?
12. The Goal!!!
13. Wheres the Java?
What?
JUnit Tests
Classes, Interfaces
Attributes
Methods
Annotations or JavaDoc
How?
Models
Reverse Engineering
Forward Engineering
(MDA) Code Generation
Top Level Component Modeling
14. Problem: Requirement management and traceability
Tracing shows progress and compliance
Tools can further use models for generation
Gaps can be analyzed
Change is manageable
Impact of change can be discovered
Requirements re-used
Once source of truth!
15. SysML Artifacts
Requirement types
Business
Design Constraint
Functional
Interface
Performance
Physical
Usability
Requirement Trace
Derived
Refines
Trace
Copy
Compliance Trace
Verify (test)
Satisfy (implementation)
Other
Containment
Notes
Comments
16. The Benefits of Modeling
Based on the use of the stereotype
Allows UML modelers to annotate elements
Instance data applied to model data
Adds additional context
Various uses
Annotations (semantics and transformation)
Planning data
Build data
Management data
Enterprise data
Requirements
17. Modeling Relationship
Dependency
Most of the relationships are base on Dependency
We have a direction from the client to the source.
If the source is removed, the client is no longer required
If the source changes, the client should meet the new source contract
18. Using SysML Requirements
Process for model-based requirements
19. Standard Requirements
20. Corporate Requirements
21. Application Requirements
22. Application Derived from Corporate Requirement
23. Augmenting Requirements
Requirements alone suck!
Use Cases
Stories (Agile)
Named User Stories (Coopers Interaction Design)
Storyboards
Class Responsibility Collaborator (CRC cards)
Activity-Based Modeling
Jackson Structured Programming (JSP)
Dont use requirements alone!
Good for discovery, bad for maintenance
Issues of clarity
Hard to allocate to work to be performed
Maintenance is difficult
Not formal
Link to requirements!
24. Use Cases
25. Refinement Trace
26. If it can fail, test it!
Everything human is at least a little bit broken.
David Weinberger from The Clue Train Manifesto
27. Verify Trace
28. Icky Sticky GUI
29. Very Sticky Requirements
30. Trace The Use Case
31. Tracing to Java!
32. Poor Traceability!!!!
33. Satisfy Trace
34. Satisfy Components
35. Capturing Other Data
Estimations
Hours
Costs
Assignments
Risks
Complexity
Unknowns
Assumptions
Priority
Customer priority
Development sequence
Success
Completed
Tested
36. Estimating and Prioritizing in the Model
37. Gaps & Tracing
38. Tracing Satisfy/Verify
39. Refined Requirements
40. Overall Process
Easy steps
Create requirements
Sort and prioritize
Allocate to your project via components
Design/Estimate/Link
Sort and prioritize
Do it!!!
Validate
Repeat
41. Focus on Development
Design/Develop Phase
Choose/Create components
Link with Requirement
Create Tests
Estimate Design
Estimate Hours/Cost
Re-wire Requirements to Tests/Classes where needed
42. 43. Take the paper out of requirements on paper
Traceability to Design
Reporting
One source of truth
Trace to the stakeholder
Simple to add metrics
Simple to add production information
Navigation between requirements and design
Automations
Automatic annotation of code
Analysis of the model
Linking to other tools
Dynamic documentation
On demand reporting
44. Java Annotations
Taking advantage of code that knows its requirements, use cases, and test cases.
45. Add Data to JavaDoc and logging
Annotate code with requirement satisfy/verify
Goal: Avoids looking at bellybutton for documentation
Synchronizes docs to code
Use annotations to inject data into logging
Can be used to annotate tests
Aid analysis
Work in progress!
46. Defining Java Annotations
47. Using Satisfy Annotation
Class has Satisfy Relationship
Other methods have not been traced to requirement
Some methods may not yet be added to inventory
48. Annotation Process
Use annotated models with data for code
Create annotations
Auto populate known relationships
Use scripting!
Use the annotation tools to change code or add info to
Source code
Logging
Improve test/debug context
Improve error messages without the work
49. Any fool can make a specification complicated. It takes skill to make it simple
50. We Are Not A Charity
Slides my boss says Im required to include
51. Youre invited for three days of:
Great networking with hundreds of architects
Multiple training sessions: UML, UPDM, SysML, SOA, Requirements, from No Magic and IASA
Leading industry keynote presentations
Three parallel tracks: Technology, Enterprise Architecture and Systems Engineering
IASA IT Architect and SysML certification programs offered during conference
52. Gaylord Texan Resort & Hotel, Grapevine, Texas
Special pricing for ITARC Austin attendees (come to our table for a one time 50%Conference discount)
53. End of part 1Thank You!
Daniel Brookshier
danielB@NoMagic.com
Can ye make a model of it? If ye can, ye understands it, and if ye canna, ye dinna!
- Lord Kelvin
54. A new road for Requirements
55. Writing Requirements
A short course!
56. Thinking Traceability
What level do you want to trace requirements
Do you add test validation results to code
Can this go both ways (inadvisable)
What other data annotates the code?
Requirement owner
Related requirements
Use Case
Other
57. Itswhere you want to go
Would you tell me please, which way I ought to go from here?
That depends a good deal on where you want to get to, said the cat.
I don't much care where -, said Alice.
Then it doesn't matter which way you go, said the cat.
Lewis Carroll, Alice in Wonderland, Chapter 6.
Quoted by Tom Gilb, Competitive Engineering
Illustration by Sir John Tenniel
58. Preventing Requirements Failure
59. People Issues
Fear of failure
Fear of success
Procrastination
Selective memory
Antidotal Evidence
Inertia
Competence in task
Politics (the bully)
60. Environmental Issues
Time
Tools
Money
Availability of experts
Organization goals
Data
61. Create Small Success
Prove your ideas
Educate
Create a chain of value
Show ROI
62. Negative Thinking is Negative
Cynicisim
Negatisim
Defeatisim
Escapisim
Delayisim
Seventy percent of consumers
read reviews.
75% say they wouldn't buy a product
after reading three negative reviews.
63. Fears
Fear of failure
Fear of success
Fear of rejection
Fear of producing low quality work
Fear of risk
Fear of pain
64. The Lizard Brain
Food
Shelter
Status
Value to the pack
65. The secret of clear requirements:
Be Brief
Less text usually leads to less confusion.
One sentence is the ideal requirement.
Broad requirements should contain specific requirements
Break down requirements to finer requirements
Divide into required (core) and optional
66. Clear and Unambiguous
Just the requirement
Dont justify
Dont give examples
Dont relate to other requirements
Dont specify implementation
Be careful of exceptions
Say what is needed, not how
67. Testable/Verifiable
Requirements need to be verifiable
What is the test?
Conditions?
Method?
Desired result?
Avoid the happy path too!
Negative conditions?
Negative results?
68. Refining Requirements
69. Give Multiple Examples
One example is easily confused with a mandate.
Two examples show possibility
Multiple examples cover expected range
Tests (positive, negative, destructive) are better
70. Who Owns It?
Document the owner
Owner should review
Include contact information
Owner should review any changes
71. Related To What?
Context is everything for many requirements
Use dependencies
When removed, eliminate need to implement
When existing, show need for related
Shows reason leading to need for requirement
Circular references are ok
72. Requirement of Requirements
Some requirements are always there
Requirements can be re-used and serve as derived or refined
Trace to other requirements:
Domain
Usability
Other parts of delivery
Technology
Corporate/Industry/Government
73. Some things are obvious
Evo - Evolutionary Project Management
Requirements Practices
Find stakeholders
Top ten requirements
Clear Requirements (Planguage)
Functional requirements
Performance Requirements
74. What is a requirement?
Ten Principalsof Requirements (Gilb)
1) The Requirement should be a Reusable Object.
2) The requirement should give information allowing us to check its quality.
3) The requirement should explicitly document its relationships to designs, tests, stakeholders, sources, use cases and all other interesting things
4) The requirement should be a future state, and not unintentionally a design to get there.
5) Complex requirements should have a clear hierarchy, not a vague summary.
75. 6) Requirements should be rich in information allowing us to determine their current priority.
7) Performance and cost requirements should contain a rich specification of targets, constraints, and time/space/event qualifiers.
8) Any class of requirement should be specified, and the classes should be well defined.
9) The requirement should be rich in information that allows us to understand, spot, analyze, present, and mitigate risks of deviation from that requirement.
10) The requirement should be easy to specify without special tools, and it should be easy for any enterprise to extend or modify the requirement language to their own purposes.
76. Challenges of Long Term Delivery
Stakeholders change
Developers change
Testers change
Tools change
Process change
Emergencies arise
Mistakes are made
Systems fail
Partners are gained
Partners are lost
Change results in changes in requirements
77. Some things never change
Stable Requirements
Usability
Efficiency
Facts
Behavior
Laws
Long term goals
Tolerating mistakes
Preventing mistakes
78. Requirements verses Refining Requirements
Requirements
Small and easy to parse
Atomic
Most are unrelated to intent, not implementation
Simple to manage
Easily integrated with models
Use case, stories, and other methods
Not atomic
Hard to parse
Usually related to implementation, not intent
Hard to manage
Harder to integrate into models
Dont confuse requirements with discovery or refining requirements
79. Can you hear me now!
First law of requirements engineering
Listen!
80. Do it all or do what you need
Information is power
Too much information is unfocused power
Too little istoo little!
81. Writing a requirement is never bad
What is bad?
Poor refinement
Wrong requirement
Poor estimates
Too many discovered in each iteration
Ignoring basic requirements
Bad programming
82. If you don't know where you're going, you're unlikely to end up there. - Forrest Gump
83. Requirement Goals
Small, implementable specifications
Measurable or testable
Easy to manage
Reusable
Traced to implementation (satisfy)
Traced to tests (verify)
See the impact of change
See gaps
84. To be stupid, selfish, and have good health are three requirements for happiness, though if stupidity is lacking, all is lost. - Gustave Flaubert
85. Any fool can make a specification complicated. It takes skill to make it simple
86. Writing Requirements
Simple is better
Atomic statements of facts/needs/goals
Generally just a sentence
Keep examples separate from the requirement
Requirements need a justification!
87. Dont overdo it
Avoid design details
Build requirements from general to specific
Dont get too specific until you are considering an iteration
Be specific about the type of requirement
Are the words testable?
88. Delivery is not necessarily the best time to discover the user requirements.- Alexander's 17th Law of Requirements
89. There are requirements and then there are requirements

There are several types of requirements

Always true
Incorrect
Forgotten/Unknown
Competitive/Situational
Requirements change due to:
Competition or events create or change business requirements
Discovered requirements during development
Errors discovered
90. There's no point in being exact about something if you don't even know what you're talking about.-John von Neumann
91. Discovering Requirements
The key to requirements is discovery
Thinking about requirements lead to related requirements
Thinking about general requirements leads to detail requirements
Thinking about design details leads to design requirements
92. Cameo ALM - Cameo RQ+
93. Architecture Werewolves Still Byte
There is no such thing as a silver bullet
Germ theory replaced mystical theories and resulted in careful process to manage health
We must replace magical thinking with process
There is no free lunch!
94. Your next step
There is only one move that really counts:
The next one.
Chess master Jose Capablanca
95. Thank You!
Can ye make a model of it? If ye can, ye understands it, and if ye canna, ye dinna!
- Lord Kelvin
96. Additional Slides
97. Agile/Scrum/XP
Requirements are still ok
With very detailed requirements Agile methodologies are unaffected and can run smoother
Easy to prioritize when requirements are complete
Variations of priorities is easier to manage within the context of pre-defined requirements
With defined requirements, establishing completion of goals is easier to prove
98. To be Agile is to use what works
Other side of the Agile coin
Tools help individuals interact and serve as a base between iterations
Documentation leads to software that meets an agreed goal
Contracts protect the customer and the supplier
A planreduces the need for change and manages it
Agile Manifesto:
Welcome changing requirements, even late in development.
Requirements Using SysML
Maintain a list of existing requirements
Know the gaps and related requirements
Use requirements to find existing code or patterns
Link with tests (Test First Methodology)
99. Those who cannot remember the past are condemned to repeat it. or by interpolation:
Those who have never heard of good system development practice are condemned to reinvent it.
Those who remember the past are doomed to a sense of dejavu.(or, if you wait long enough, engineering fashion will come round again)
- Martin Feather
100. Plan-Do-Study-Act (PDSA)Shewhart/Deming
Plan: Requirements
Do: Which, and when!
Study: How much and how well
Act: Produce!
101. Plan-Do-Study-Act (PDSA) Shewhart/Deming
PDSA is process
Plan it
Do it
Observing results
Refactor as needed
Simple concepts
Each step important
No shortcuts
No Magic
Just Hard Work
102. Plan & Do
Step 1: Plan
Plan the test or observation, including a plan for collecting data.
State the objective of the test.
Make predictions about what will happen and why.
Develop a plan to test the change. (Who? What? When? Where? What data need to be collected?)
Step 2: Do
Tryout the test on a small scale.
Carry out the test.
Document problems and unexpected observations.
Begin analysis of the data.
103. Study & Act
Step 3: Study
Set aside time to analyze the data and study the results.
Complete the analysis of the data.
Compare the data to your predictions.
Summarize and reflect on what was learned.
Step 4: Act
Refine the change, based on what was learned from the test.
Determine what modifications should be made.
Prepare a plan for the next test.
104. Agile and the Pyramid
A fantasy wrapped in misdirection
105. Agile Manifesto
Agile Manifesto
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
Agile does help stop abuse, but you can go too far!
No process or tools leads to anarchy and lack of accounting
No documentation causes confusion and more anarchy
Lack of contracts lack of payment
No plan leads to reactive change missing long term goals
106. Pyramid of Agile
Problems with the Agile pyramid (Alex Papadimoulis)
Doesnt work well for the 3D shape
What about the foundation?
Inner chamber design limited to initial build
Key points:
Tough to do with stone
The plan is important (for either goal)
What pharaoh is going to settle for the smaller pyramid?
This story is a story, a lie
107. The Rebuttal (Bex Huff)
Software architecture is not architecture (software vs physical)
Buildings always have a custom foundation (yikes!)
You can patch a building with very few side effects
Enabling communication between 2 buildings rarely causes their destruction
Plumbing and waterworks design is a much better analogy, and not just because the internet is full of tubes
So, Agile supporters use a false building analogy
Anti-agile supporter tears it down with an understanding of buildings
Agile supporter says building analogies are a scam because software is not a building, but pluming
Truth: Software is not simple and under thinking is folly
108. Software and hard drugs are the only two professions that refer to their customers as 'users'.
- Anon
109. For a successful technology, reality must take precedence over public relations, for nature cannot be fooled.
Richard P Feynman (during the Challenger inquiry)
110. Writing Requirements
The cobbler's children go unshod.
which of course means:
Requirements Engineers never write down their their own requirements.
111. Tests for Requirements
112. Observation
113. Input Causes Output
114. Action Causes Reaction
115. Performance
116. Accuracy
117. Transformation Reversibility
118. Usability Metrics