Requirements Writing for System Engineering (eBook)

George Koelsch is a system engineer who resides in Northern Virginia within the DC metro area. He started writing requirements 40 years ago while in the US Army, and has continued that work for the last 30 years as a contractor for the Federal Government. He became an efficiency expert during a five year stint as an Industrial Engineer at Michelin Tire Corporation, and he then applied that new skill to system engineering to tailor the lifecycle development process. He was among the first requirement engineers in the DC area to employ such a technique. Koelsch has authored ten non-fiction articles on computers, coin collecting, stamp collecting, and high-energy physics. He recently decided to combine his two passions, system engineering and writing.

Contents at a Glance 5
Contents 7
About the Author 21
Acknowledgments 22
Part I: The Foundation of Requirements 23
Chapter 1: The Importance of Requirements 24
Requirements Conventions Used in the Book 26
Projects Used in This Book 27
FBI Record Management Project 28
Radiation Dosimetry Project 28
Basic Definitions 29
Definitions of Requirements-Related Terms 29
How Long Does It Take Requirements Engineers to… 30
What Makes a Good RE? 32
Personality Traits 32
Patience 32
Clarity of Thought 33
Flexibility 35
Extrovertism 35
Confidence 36
Negative Traits 37
Good Communications Skills 38
Responsiveness 38
Translator 39
Moderator 39
Persuasiveness 40
Summary 40
Challenges for Writing Effective Requirements 40
Insufficient Requirements 40
Scope 42
Requirements Creep 43
Volatility 43
Stove-Piped Requirements 44
Users Are Not Sure What They Need 45
User Needs Not Satisfied 46
Multiple Interpretations Cause Disagreements 47
Are the Requirements Verifiable? 47
Wasted Time and Resources Building the Wrong Functions 48
Summary 49
References 50
Exercises 50
Exercise 1 50
Exercise 2 50
Chapter 2: What Makes a Good Requirement? 51
Understanding Requirements 51
The Form of a Requirement 51
Dealing with Negatives in Requirements 53
Attributes of a Good Requirement 54
Accurate 56
Atomic 56
Parent-Child Requirements 57
Complete 58
Completeness of an Individual Requirement 58
Completeness of a Group of Requirements 60
Concise 63
Consistent 64
Does Not Conflict with Other Requirements 66
Does Not Duplicate Other Requirements 67
Independent 68
Stand on Its Own 68
Implementation Independent 69
Prioritized 71
Realistic 73
Traceable 75
Traceability 75
Traced to a Source 76
Unambiguous 78
Ambiguity in General 78
Subjective Terminology 80
Troublesome Parts of Speech 81
Passive Voice 83
Understandable by Stakeholders 84
Unique 86
Verifiable 86
Testing 87
Inspection 88
Demonstration 88
Simulation 89
Analysis 89
Wrap-Up of Verifiable 90
One More Attribute: Modifiable 90
Capability Within a Requirement 91
Types of Errors That Can Occur with Requirements 91
Dangerous or Toxic Requirements 92
Extra, Superfluous Requirements 92
Incomplete Requirements 92
Others 93
References 93
Exercises 93
Exercise 1 93
Exercise 2 94
Exercise 3 94
Exercise 4 94
Exercise 5 94
Chapter 3: Specialized Language 95
The Use of Language 95
Defining Specialized Terms 97
Acronyms and Abbreviations 98
Summary 100
Exercises 100
Exercise 1 100
Exercise 2 100
Part II: Types of Requirements 101
Chapter 4: Functional Requirements 102
Understanding Types of Requirements 102
Types of Functional Requirements 103
Business Rules 104
Transactions 105
Transaction Entry 105
Transaction Change 106
Transaction Errors 106
Administrative Functions 107
Authentication 108
Authorization Levels 109
Audit Tracking 110
External Interfaces 111
Certification Requirements 112
Searching and Reporting Requirements 113
Compliance, Legal, or Regulatory Requirements 116
Historical Data 117
Archiving 118
Structural 119
Algorithms 120
Database 120
Power 121
Network 122
Infrastructure 122
Backup and Recovery 123
Summary 124
Exercises 124
Exercise 1 124
Exercise 2 124
Chapter 5: Nonfunctional Requirements 125
The Types of Nonfunctional Requirements 125
Architectural 126
Capacity 127
Constraints 128
Documentation 129
Efficiency 129
Effectiveness 130
Fault Tolerance 130
Privacy 131
Quality 131
Resilience 132
Robustness 132
Environmental 133
Data Integrity 133
Standards 133
Performance 134
Performance Response Time 135
Workload Performance 136
Platform Performance 137
Performance Profiles 137
Throughput 138
Reliability, Availability, and Maintainability (RAM) 139
Definitions 139
Mean Time to Repair (MTTR) 140
Wait Time 140
Mean Time Between Failures (MTBF) 140
Availability 140
Maintainability 142
Mean Time to Maintain (MTTM) 142
Mean Time Between Maintenance (MTBM) 142
Reliability 144
Failure Definition 145
Security 147
Access Control 148
Import From and Export to Outside the System 149
Connections to Outside the System 150
Reuse 152
Scalability 154
Usability 157
Accessibility 158
Interoperability 159
Portability 160
Stability 161
Supportability 162
Testability 162
Recoverability 163
Serviceability 163
Manageability 164
Summary 164
References 165
Exercises 165
Exercise 1 165
Exercise 2 165
Exercise 3 165
Exercise 4 165
Exercise 5 166
Exercise 6 166
Exercise 7 166
Exercise 8 166
Exercise 9 167
Exercise 10 167
Exercise 11 167
Chapter 6: Lists of Items and the Order of Steps and Data Elements 168
Lists of Items in Requirements 168
Lists of Data Elements 172
Diagnostics Request 173
Diagnostics Response 174
Image Request Message 176
Image Response Message 176
Order of Steps in Requirements 181
Order of Data Elements in Requirements 183
Exercises 184
Exercise 1 184
Exercise 2 185
Chapter 7: Data Interfaces and Documents 186
Defining Requirement Data Elements 186
Defining Data Elements Within a Requirement 186
Defining Data Elements Within a Database 188
Interface Control Documents 191
Input/Outputs 194
Outputs 194
Inputs 196
Transformations 197
Interface Control Document Formats 198
HUD Guidelines for the Data Requirements Document Checklist 199
DoD 201
MIL-STD 962D (Military Standard) 201
Foreword 202
8.4.2.2 DI-SDMP-81470 Department of Defense (DoD) Interface Standard Documents 202
NASA Training Manual for Elements of Interface Definition and Control 204
Centers for Medicare & Medicaid Services CMS eXpedited Life Cycle (XLC)
References 210
Exercises 211
Exercise 1 211
Exercise 2 211
Chapter 8: Physical Requirements 212
Physical Hardware Characteristics 212
Overall Weight 213
Size 213
Geometric Shape 214
Volume 215
Density 215
Center of Gravity 215
Human Portable 216
Safety Features 216
Storage 217
Packaging, Cooling, Heating, and Integration Constraints 217
Power Consumption 218
Material 218
Surface Coefficient of Friction 219
Physical Robustness 219
Reliability 219
Throughput 219
Physical Computer Characteristics 220
Throughput Characteristics 221
Throughput 221
Latency 223
References 224
Exercises 224
Exercise 1 224
Exercise 2 224
Part III: Cradle to Grave Requirements 225
Chapter 9: How to Collect Requirements 226
Elicitation 227
Techniques of Elicitation 228
Elicitation Basics 228
Requirements Sources 228
Stakeholders 229
Documents 229
System in Operation 229
An Overview of Elicitation Techniques 229
Questionnaires/Surveys 231
Group Meetings 232
Facilitated Session 232
Focus Group 233
Joint Application Development/Requirements Workshop 233
Support Teams 233
Brainstorming 234
Interviewing 235
Size of Interviews Vary 235
In-Person, Telephone, Videoconference, and Online Interviews 236
Segregate by User Roles 236
Running an Interview 237
Things That Enhance the Interview 238
Listening 239
Things Change Over Time 239
Glossaries 239
Note Taking 239
Follow-Up Questions 240
Missing Knowledge 240
Cultural/Language Differences 241
Following People Around/Observation 241
Models 242
Document Analysis 242
Business Process 243
Existing Requirements 243
Existing Interface Documents 244
Design Documents 244
Manuals: User, Operations, Training, and Help 244
Identified Problems and Changes 244
Competing or Analogous Systems 245
Prototyping 246
Use Cases/Scenarios/User Stories 246
Working in the Target Environment 247
Request for Proposals 247
Reverse Engineering 247
Tools 248
Purpose of Elicitation 249
Defining the Scope of the System 249
Gaining Domain Knowledge 249
Deciding On the Elicitation Techniques to Use 250
Eliciting the Requirements 250
Performing a Gap Analysis 252
Completing the Requirements 252
Problems with Elicitation 253
Problems of Scope 254
The Boundary of the System Is Ill-Defined 254
Unnecessary Design Information May Be Given 254
Problems of Understanding 254
Users Have an Incomplete Understanding of Their Needs 254
Users Have Poor Understanding of Computer Capabilities and Limitations 255
Analysts Have Poor Knowledge of Problem Domain 255
User and Analyst Speak Different Languages 255
Ease of Omitting “Obvious” Information 256
Conflicting Views of Different Users 256
Requirements Are Often Vague and Untestable 256
Problems of Volatility: Requirements Evolve 256
Requirements Evolve Over Time 256
Process Improvement 256
References 258
Exercises 258
Exercise 1 258
Exercise 2 258
Chapter 10: User Interface Requirements 259
Introducing UI Requirements 259
Improving the User Interface 261
Government UI Improvements 261
Candidate UI Topics for Requirements 263
Error Conditions 264
Human Factors 265
Section 508 Compliance 267
References 268
Exercises 269
Exercise 1 269
Chapter 11: Managing Requirements 270
Why Should You Manage Requirements? 270
A Bit of a History Lesson 271
What Types of Tools Should You Consider? 272
Attributes of Effective Requirement Management Tools 273
The Tools 274
Rating of the Tools 274
Importing 277
What Requirement Values Should You Manage? 278
Requirements Fields 278
Requirements Associated with Testing Fields 283
Requirements Associated with Agile Fields 283
References 284
Exercises 285
Exercise 1 285
Exercise 2 285
Exercise 3 285
Part IV: Alternatives to Shall Requirements 286
Chapter 12: Supplementing or Replacing Standard Requirements 287
User Stories and Use Cases 288
User Stories 288
Use Cases 289
Supplementing Your Requirements 291
Replacements for Requirements 291
Modeling 292
General Modeling 293
Models for Ordinary Requirements 294
Swim Lanes 294
Data Flow Diagrams (DFDs) 296
Specialized Modeling 299
Tools That Can Aid Requirements Gathering 300
Affinity Diagrams 300
Storyboarding 301
Other Supplements to Requirements Process 306
Off-the-Shelf Solutions 306
IEEE Standards 308
ISO 9001:2008 309
CMM/CMMI Levels of Maturity 309
INCOSE 311
References 311
Chapter 13: User Stories 313
Anatomy of a User Story 313
Parts of a User Story 313
Attributes of a User Story 315
Independent 316
Negotiable 317
Valuable 319
Estimable 320
Small 322
Testable 325
Acceptance Criteria 326
Size of stories 328
Complement vs. Supplement to Requirements 330
Complement to Requirements 330
Replacement for Requirements 331
User Stories Traceability 331
Maintain User Stories 334
What Can Go Wrong with Writing User Stories? 335
Summary 337
References 337
Exercises 338
Exercise 1 338
Exercise 2 338
Exercise 3 338
Exercise 4 338
Exercise 5 338
Exercise 6 338
Chapter 14: Use Cases 339
Writing Use Cases 339
Use Case Sequence 339
Login Use Case 341
Unit Dosimetry Report Use Case 348
Gap Analysis 352
Advantages and Disadvantages of Use Cases 354
Advantages 355
Disadvantages 356
Complement vs. Replacement to Requirements 358
Complement to Requirements 358
Replacement for Requirements 359
All Three Together 360
References 360
Exercises 360
Exercise 1 360
Exercise 2 360
Chapter 15: Revisiting Requirement Problems and Their Solutions 361
Insufficient Requirements 361
Requirements Creep 362
Volatility 362
Stove-Piped Requirements 363
Scope: Boundaries Can Be Ill-Defined 363
Understanding Users Are Not Sure What They Need 364
May Not Satisfy User Needs 365
Misinterpretation: Cause Disagreements 365
Cannot Verify the Requirements 366
Wasted Time and Resources Building the Wrong Functions 367
Summary 367
Exercises 368
Exercise 1: 368
Exercise 2: 368
Exercise 3: 368
Part V: Appendixes 369
Appendix A: Acronyms and Abbreviations 370
Appendix B: Requirements Documents 375
DoD FRD Template 375
FUNCTIONAL REQUIREMENTS DOCUMENT (FRD) FOR DEPARTMENT OF DEFENSE (DOD) < PROJECT NAME>
Comments on This DoD FRD 377
IEEE Document Formats 377
Final Comments on Requirements Document Formats 377
References 378
Appendix C: Section 508 Compliance 379
The Background for Section 508 379
Background 379
Exemptions to Section 508 380
Section 1194.3 General Exceptions 380
Section 508 Technical Standards 380
Subpart B – Technical Standards 380
§ 1194.21 Software Applications and Operating Systems 380
§ 1194.22 Web-based Intranet and Internet Information and Applications 381
§ 1194.23 Telecommunications Products 383
§ 1194.24 Video and Multimedia Products 384
§ 1194.25 Self-contained, Closed Products 385
§ 1194.26 Desktop and Portable Computers 386
Section 508 Functional Performance Criteria 387
Subpart C – Functional Performance Criteria 387
§ 1194.31 Functional Performance Criteria 387
Section 508 Information, Documentation, and Support 387
Subpart D – Information, Documentation, and Support 388
§ 1194.41 Information, Documentation, and Support 388
Glossary 389
Bibliography 398
Index 402