requirements writing for system engineering
TRANSCRIPT
RequirementsWriting for System
Engineering
George Koelsch
Apress
Contents
JAbout the Author xxi
Acknowledgments xxiii
Part I: The Foundation of Requirements....... 1
^Chapter 1: The Importance of Requirements..... 3
Requirements Conventions Used in the Book 5
Projects Used in This Book.. 6
FBI Record Management Project 7
Radiation Dosimetry Project 7
Basic Definitions 8
Definitions of Requirements-Related Terms 8
How Long Does It Take Requirements Engineers to 9
What Makes a Good RE? 11
Personality Traits 11
Good Communications Skills 17
Summary 19
Challenges for Writing Effective Requirements 19
Insufficient Requirements 19
Scope • • 21
Requirements Creep 22
Volatility 22
Stove-Piped Requirements 23
vii
CONTENTS
Users Are Not Sure What They Need 24
User Needs Not Satisfied 25
Multiple Interpretations Cause Disagreements 26
Are the Requirements Verifiable? 26
Wasted Time and Resources Building the Wrong Functions 27
Summary 28
References 29
Exercises 29
Exercise 1 29
Exercise 2 29
Chapter 2: What Makes a Good Requirement? 31
Understanding Requirements 31
The Form of a Requirement 31
Dealing with Negatives in Requirements 33
Attributes of a Good Requirement 34
Accurate 36
Atomic 36
Complete 38
Concise 43
Consistent 44
Does Not Conflict with Other Requirements 46
Does Not Duplicate Other Requirements 47
Independent 48
Prioritized 51
Realistic 53
Traceable 55
Unambiguous 58
Understandable by Stakeholders 64
viii
CONTENTS
Unique 66
Verifiable 66
One More Attribute: Modifiable 70
Capability Within a Requirement 71
Types of Errors That Can Occur with Requirements 71
Dangerous or Toxic Requirements 72
Extra, Superfluous Requirements 72
incomplete Requirements 72
Others 73
References ...73
Exercises 73
Exercise 1 73
Exercise 2 74
Exercise 3 74
Exercise 4 74
Exercise 5 74
iChapter 3: Specialized Language 75
The Use of Language 75
Defining Specialized Terms 77
Acronyms and Abbreviations 78
Summary 80
Exercises 80
Exercise 1 80
Exercise 2 80
ix
CONTENTS
Part II: Types of Requirements 81
Chapter 4: Functional Requirements..... 83
Understanding Types of Requirements 83
Types of Functional Requirements 84
Business Rules 85
Transactions 86
Administrative Functions 88
Authentication 89
Authorization Levels 90
Audit Tracking 91
External Interfaces 92
Certification Requirements 93
Searching and Reporting Requirements 94
Compliance, Legal, or Regulatory Requirements 97
Historical Data 98
Archiving 99
Structural 100
Algorithms 101
Database 101
Power 102
Network 103
Infrastructure 103
Backup and Recovery 104
Summary 105
Exercises 105
Exercise 1 105
Exercise 2 105
x
CONTENTS
Chapter 5: Nonfunctional Requirements...... 107
The Types of Nonfunctional Requirements 107
Architectural 108
Capacity 109
Constraints 110
Documentation 111
Efficiency 111
Effectiveness 112
Fault Tolerance 112
Privacy 113
Quality 113
Resilience 114
Robustness 114
Environmental
Data Integrity 115
Standards 115
Performance 11fi
Reliability, Availability, and Maintainability (RAM) 121
Security 129
Scalability t36
Usability 139
Accessibility - I40
Interoperability 141
Portability t42
Stability 143
Supportability I44
Testability 144
Recoverability 145
Serviceability 145
Manageability 146
xi
mCONTENTS
Summary 146
References 147
Exercises 147
Exercise 1 147
Exercise 2 147
Exercise 3 147
Exercise 4 147
Exercise 5 148
Exercise 6 148
Exercise 7 148
Exercises 148
Exercise 9 ..149
Exercise 10 149
Exercise 11 149
Chapter 6: Lists of Items and the Order of
Steps and Data Elements.. 151
Lists of Items in Requirements 151
Lists of Data Elements 155
Diagnostics Request 156
Diagnostics Response 157
Image Request Message 159
Image Response Message 159
Order of Steps in Requirements 164
Order of Data Elements in Requirements 166
Exercises ...167
Exercise 1 167
Exercise 2 168
xii
CONTENTS
Chapter 7: Data Interfaces and Documents 169
Defining Requirement Data Elements 169
Defining Data Elements Within a Requirement 169
Defining Data Elements Within a Database 171
Interface Control Documents 174
Input/Outputs 177
Outputs .177
Inputs 179
Transformations 180
Interface Control Document Formats 181
HUD Guidelines for the Data Requirements Document Checklist 182
DoD 184
NASA Training Manual for Elements of Interface Definition and Control 187
Centers for Medicare & Medicaid Services CMS expedited Life Cycle (XLC).... 192
References 193
Exercises 194
Exercise 1 194
Exercise 2 194
{Chapter 8: Physical Requirements 195
Physical Hardware Characteristics 195
Overall Weight 196
Size 196
Geometric Shape 197
Volume 198
Density 198
Center of Gravity 198
Human Portable 199
Safety Features 199
xiii
CONTENTS
Storage 200
Packaging, Cooling, Heating, and integration Constraints 200
Power Consumption 201
Material 201
Surface Coefficient of Friction 202
Physical Robustness 202
Reliability 202
Throughput 202
Physical Computer Characteristics 203
Throughput Characteristics 204
Throughput 204
Latency 206
References 207
Exercises 207
Exercise 1 207
Exercise 2 207
Part III: Cradle to Grave Requirements 209
Chapter 9: How to Collect Requirements..... 211
Elicitation. 212
Techniques of Elicitation 213
Elicitation Basics 213
Requirements Sources 213
An Overview of Elicitation Techniques 214
Questionnaires/Surveys 216
Group Meetings •217
Interviewing 220
Following People Around/Observation 226
Models 227
xiv
CONTENTS
Document Analysis 227
Prototyping 231
Use Cases/Scenarios/User Stories 231
Working in the Target Environment 232
Request for Proposals 232
Reverse Engineering 232
Tools 233
Purpose of Elicitation 234
Problems with Elicitation 238
Problems of Scope 239
Problems of Understanding 239
Problems of Volatility: Requirements Evolve 241
Process Improvement 241
References 243
Exercises 243
Exercise 1 243
Exercise 2 243
Chapter 10: User Interface Requirements... 245
Introducing Ul Requirements. 245
Improving the User Interface 247
Government Ul Improvements 247
Candidate Ul Topics for Requirements 249
Error Conditions •250
Human Factors 251
Section 508 Compliance 253
References 254
Exercises 255
Exercise 1 255
XV
CONTENTS
Chapter 11: Managing Requirements 257
Why Should You Manage Requirements? 257
A Bit of a History Lesson 258
What Types of Tools Should You Consider? 259
Attributes of Effective Requirement Management Tools 260
The Tools 261
Rating of the Tools -261
Importing 264
What Requirement Values Should You Manage? 265
Requirements Fields 265
Requirements Associated with Testing Fields 270
Requirements Associated with Agile Fields 270
References 271
Exercises 272
Exercise 1 272
Exercise 2 272
Exercise 3 -272
Part IV: Alternatives to Shall Requirements 273
aChapter 12: Supplementing or ReplacingStandard Requirements 275
User Stories and Use Cases 276
User Stories,
276
Use Cases 277
Supplementing Your Requirements 279
Replacements for Requirements 279
xvi
CONTENTS
Modeling 280
General Modeling . 281
Models for Ordinary Requirements 282
Specialized Modeling 287
Tools That Can Aid Requirements Gathering 288
Other Supplements to Requirements Process 294
Off-the-Shelf Solutions 294
IEEE Standards... 296
ISO 9001:2008.... 297
CMM/CMMI Levels of Maturity 297
INCOSE 299
References 299
Chapter 13: User Stories 301
Anatomy of a User Story 301
Parts of a User Story 301
Attributes of a User Story 303
Acceptance Criteria... 314
Size of stories 316
Complement vs. Supplement to Requirements 318
Complement to Requirements 318
Replacement for Requirements 319
User Stories Traceability.. 319
Maintain User Stories 322
What Can Go Wrong with Writing User Stories? 323
Summary 325
References 325
xvii
V-;: CONTENTS
Exercises 326
Exercise 1 326
Exercise 2 326
Exercise 3 326
Exercise 4 ...326
Exercise 5 326
Exercise 6 326
Chapter 14: Use Cases 327
Writing Use Cases 327
Use Case Sequence 327
Login Use Case -329
Unit Dosimetry Report Use Case 336
Gap Analysis 340
Advantages and Disadvantages of Use Cases....,
342
Advantages 343
Disadvantages 344
Complement vs. Replacement to Requirements 346
Complement to Requirements 346
Replacement for Requirements 347
All Three Together 348
References 348
Exercises 348
Exercise 1 348
Exercise 2 348
Chapter 15: Revisiting Requirement Problems and
Their Solutions 349
Insufficient Requirements 349
Requirements Creep 350
xviii
CONTENTS
Volatility.... 350
Stove-Piped Requirements 351
Scope: Boundaries Can Be Ill-Defined 351
Understanding Users Are Not Sure What They Need 352
May Not Satisfy User Needs 353
Misinterpretation: Cause Disagreements 353
Cannot Verify the Requirements 354
Wasted Time and Resources Building the Wrong Functions 355
Summary 355
SPart V: Appendixes 357
Appendix A: Acronyms and Abbreviations 359
Appendix B: Requirements Documents 365
DoD FRD Template 365
FUNCTIONAL REQUIREMENTS DOCUMENT (FRD) FOR DEPARTMENT
OF DEFENSE (DOD) <PR0JECT NAME> 366
Comments on This DoD FRD 367
IEEE Document Formats 367
Final Comments on Requirements Document Formats 367
References 368
Appendix C: Section 508 Compliance 369
The Background for Section 508 369
Background 369
Exemptions to Section 508 370
Section 1194.3 General Exceptions 370
Section 508 Technical Standards 370
Subpart B - Technical Standards 370
xix
2 CONTENTS
Section 508 Functional Performance Criteria 377
Subpart C - Functional Performance Criteria 377
Section 508 Information, Documentation, and Support 377
Subpart D - Information, Documentation, and Support 378
Glossary 379
Bibliography .....389
Index 393
XX