21
Requirements Writing for System Engineering George Koelsch
Requirements Writing for System
Engineering
George Koelsch
Requirements Writing for System Engineering
George Koelsch Herndon, Virginia, USA
ISBN-13 (pbk): 978-1-4842-2098-6 ISBN-13 (electronic): 978-1-4842-2099-3DOI 10.1007/978-1-4842-2099-3
Library of Congress Control Number: 2016956399
Copyright © 2016 by George Koelsch
This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed.
Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark.
The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights.
While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material contained herein.
Managing Director: Welmoed SpahrLead Editor: Jonathan GennickDevelopment Editor: Chris NelsonEditorial Board: Steve Anglin, Pramila Balan, Laura Berendson, Aaron Black,
Louise Corrigan, Jonathan Gennick, Todd Green, Robert Hutchinson, Celestin Suresh John, Nikhil Karkal, James Markham, Susan McDermott, Matthew Moodie, Natalie Pao, Gwenan Spearing
Coordinating Editor: Jill BalzanoCopy Editor: Kim WimpsettCompositor: SPi GlobalIndexer: SPi GlobalArtist: SPi Global
Distributed to the book trade worldwide by Springer Science+Business Media New York, 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail [email protected] , or visit www.springer.com . Apress Media, LLC is a California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation.
For information on translations, please e-mail [email protected] , or visit www.apress.com .
Apress and friends of ED books may be purchased in bulk for academic, corporate, or promotional use. eBook versions and licenses are also available for most titles. For more information, reference our Special Bulk Sales–eBook Licensing web page at www.apress.com/bulk-sales .
Any source code or other supplementary materials referenced by the author in this text are available to readers at www.apress.com . For detailed information about how to locate your book’s source code, go to www.apress.com/source-code/ . Readers can also access source code at SpringerLink in the Supplementary Material section for each chapter.
Printed on acid-free paper
Th is is dedicated to the people who work to protect others around the world, men and women, military and civilian, especially those I served with in Afghanistan
(yes, you too, Blue Devil).
v
Contents at a Glance
About the Author ............................................................................ xxi
Acknowledgments ........................................................................ xxiii
■Part I: The Foundation of Requirements ......................... 1
■Chapter 1: The Importance of Requirements .................................. 3
■Chapter 2: What Makes a Good Requirement? ............................. 31
■Chapter 3: Specialized Language ................................................. 75
■Part II: Types of Requirements ..................................... 81
■Chapter 4: Functional Requirements ............................................ 83
■Chapter 5: Nonfunctional Requirements ..................................... 107
■ Chapter 6: Lists of Items and the Order of Steps and Data Elements ............................................................ 151
■Chapter 7: Data Interfaces and Documents ................................ 169
■Chapter 8: Physical Requirements ............................................. 195
■Part III: Cradle to Grave Requirements ....................... 209
■Chapter 9: How to Collect Requirements .................................... 211
■Chapter 10: User Interface Requirements .................................. 245
■Chapter 11: Managing Requirements ......................................... 257
■ CONTENTS AT A GLANCE
vi
■Part IV: Alternatives to Shall Requirements ............... 273
■ Chapter 12: Supplementing or Replacing Standard Requirements .............................................................. 275
■Chapter 13: User Stories ............................................................. 301
■Chapter 14: Use Cases ................................................................ 327
■ Chapter 15: Revisiting Requirement Problems and Their Solutions ........................................................................... 349
■Part V: Appendixes ..................................................... 357
■Appendix A: Acronyms and Abbreviations ................................. 359
■Appendix B: Requirements Documents ...................................... 365
■Appendix C: Section 508 Compliance ......................................... 369
■Glossary ...................................................................................... 379
■Bibliography ............................................................................... 389
Index .............................................................................................. 393
vii
Contents
About 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 Defi nitions ..................................................................................... 8
Defi nitions 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
Insuffi cient Requirements ...................................................................................... 19
Scope ...................................................................................................................... 21
Requirements Creep ............................................................................................... 22
Volatility .................................................................................................................. 22
Stove-Piped Requirements ..................................................................................... 23
■ CONTENTS
viii
Users Are Not Sure What They Need ....................................................................... 24
User Needs Not Satisfi ed ........................................................................................ 25
Multiple Interpretations Cause Disagreements ...................................................... 26
Are the Requirements Verifi able? ........................................................................... 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 Confl ict with Other Requirements ........................................................... 46
Does Not Duplicate Other Requirements ................................................................ 47
Independent ............................................................................................................ 48
Prioritized ............................................................................................................... 51
Realistic .................................................................................................................. 53
Traceable ................................................................................................................ 55
Unambiguous .......................................................................................................... 58
Understandable by Stakeholders ............................................................................ 64
■ CONTENTS
ix
Unique .................................................................................................................... 66
Verifi able ................................................................................................................. 66
One More Attribute: Modifi able .............................................................................. 70
Capability Within a Requirement ........................................................... 71
Types of Errors That Can Occur with Requirements .............................. 71
Dangerous or Toxic Requirements .......................................................................... 72
Extra, Superfl uous 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
■Chapter 3: Specialized Language ................................................. 75
The Use of Language ............................................................................. 75
Defi ning Specialized Terms ................................................................... 77
Acronyms and Abbreviations ................................................................. 78
Summary ............................................................................................... 80
Exercises ............................................................................................... 80
Exercise 1 ............................................................................................................... 80
Exercise 2 ............................................................................................................... 80
■ CONTENTS
x
■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
Certifi cation 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
■ CONTENTS
xi
■Chapter 5: Nonfunctional Requirements ..................................... 107
The Types of Nonfunctional Requirements .......................................... 107Architectural ......................................................................................................... 108
Capacity ................................................................................................................ 109
Constraints ........................................................................................................... 110
Documentation ..................................................................................................... 111
Effi ciency .............................................................................................................. 111
Effectiveness ........................................................................................................ 112
Fault Tolerance ..................................................................................................... 112
Privacy .................................................................................................................. 113
Quality................................................................................................................... 113
Resilience ............................................................................................................. 114
Robustness ........................................................................................................... 114
Environmental ....................................................................................................... 115
Data Integrity ........................................................................................................ 115
Standards ............................................................................................................. 115
Performance ......................................................................................................... 116
Reliability, Availability, and Maintainability (RAM) ................................................. 121
Security ................................................................................................................ 129
Scalability ............................................................................................................. 136
Usability ................................................................................................................ 139
Accessibility .......................................................................................................... 140
Interoperability ..................................................................................................... 141
Portability ............................................................................................................. 142
Stability ................................................................................................................. 143
Supportability ....................................................................................................... 144
Testability ............................................................................................................. 144
Recoverability ....................................................................................................... 145
Serviceability ........................................................................................................ 145
Manageability ....................................................................................................... 146
■ CONTENTS
xii
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
Exercise 8 ............................................................................................................. 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
■ CONTENTS
xiii
■Chapter 7: Data Interfaces and Documents ................................ 169
Defi ning Requirement Data Elements ................................................. 169
Defi ning Data Elements Within a Requirement ..................................................... 169
Defi ning 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 Defi nition 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
■ CONTENTS
xiv
Storage ................................................................................................................. 200
Packaging, Cooling, Heating, and Integration Constraints .................................... 200
Power Consumption ............................................................................................. 201
Material ................................................................................................................ 201
Surface Coeffi cient 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
■ CONTENTS
xv
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 UI Requirements ............................................................... 245
Improving the User Interface ............................................................... 247
Government UI Improvements .............................................................................. 247
Candidate UI Topics for Requirements .................................................................. 249
Error Conditions .................................................................................................... 250
Human Factors ..................................................................................................... 251
Section 508 Compliance ...................................................................... 253
References .......................................................................................... 254
Exercises ............................................................................................. 255
Exercise 1 ............................................................................................................. 255
■ CONTENTS
xvi
■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
■ Chapter 12: Supplementing or Replacing Standard Requirements .............................................................. 275
User Stories and Use Cases ................................................................ 276
User Stories .......................................................................................................... 276
Use Cases ............................................................................................................. 277
Supplementing Your Requirements ...................................................................... 279
Replacements for Requirements .......................................................................... 279
■ CONTENTS
xvii
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
■ CONTENTS
xviii
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
Insuffi cient Requirements ................................................................... 349
Requirements Creep ............................................................................ 350
■ CONTENTS
xix
Volatility ............................................................................................... 350
Stove-Piped Requirements .................................................................. 351
Scope: Boundaries Can Be Ill-Defi ned ................................................. 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
■Part 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) <PROJECT 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
■ CONTENTS
xx
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
xxi
About the Author
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 U.S. Army and has continued that work for the last 30 years as a contractor for the federal government. With a five-year stint as an industrial engineer at Michelin Tire Corporation, he learned to become an efficiency expert, which he then applied to system engineering to tailor the lifecycle development process before his contemporaries in the DC area were . In his spare time, he authored ten nonfiction articles on computers, coin collecting, stamp collecting, and high-energy physics. He decided to combine his two passions, system engineering and writing recently.
xxiii
Acknowledgments
Over my career spanning four decades, I have worked with hundreds of people, many who helped mentor me in this field of system engineering, with a strong focus on requirements engineering, even before we called it that. To name all those people would produce too numerous a list, even if I could remember all their names, which unfortunately I cannot. Many of them when they read this book will recognize their contribution, and I hope that is sufficient, for that is all I can provide at this point.
That said, there is one individual who I would like to recognize for his contribution. I had been planning to write this book for some time; I was just not certain when I would begin. Over the last decade or so, I have been mentoring others in the fine art of requirements engineering. I had noted that the requirements books I had, as well as others I had read, did not measure up to my standard of what I thought a requirements book should be. I mentioned it to one particular co-worker who promptly said that I should write that book. That person is Adam Heath. It clicked. That was the time to start writing. So I did. Not only was he the spark for this project, but because of his background in book publishing, especially IT, his guidance has proved invaluable. He guided me through the query letter, book proposal, and refinement of the book itself. Adam, I cannot give you enough kudos.
Jonathan Gennick, the assistant editorial director at Apress, initially discovered me on behalf of one of the best IT publishing firms in the world, Apress, and worked with me to get the manuscript into the book it is. Jill Balzano, the project manager at Apress, worked with me throughout the entire day-to-day process from the initial upload until the book appeared in my hand. She never tired of the endless questions I had, answered them gladly, and kept everything moving along smoothly. The one person who made this text a much better book by his development editor tutelage is Chris Nelson. He taught me so much about writing a technical book that I cannot begin to mention. If you find this an excellent book, it is because of Chris. On the other hand, if there is any deficiency, it falls to me. To all the other people at Apress who I may not even be aware of, thank you so much. Each of you contributed to this book.
And, to all the other unnamed people out there, thank you.
