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