Koelsch Requirements Writing for System Engineering

1. ed
ISBN: 978-1-4842-2099-3
Verlag: Apress
Format: PDF
Kopierschutz: 1 - PDF Watermark

E-Book, Englisch, 409 Seiten

Learn how to create good requirements when designing hardware and software systems. While this book emphasizes writing traditional 'shall' statements, it also provides guidance on use case design and creating user stories in support of agile methodologies. The book surveys modeling techniques and various tools that support requirements collection and analysis. You'll learn to manage requirements, including discussions of document types and digital approaches using spreadsheets, generic databases, and dedicated requirements tools. Good, clear examples are presented, many related to real-world work the author has done during his career. Requirements Writing for System Engineeringantages of different requirements approaches and implement them correctly as your needs evolve. Unlike most requirements books, Requirements Writing for System Engineering teaches writing both hardware and software requirements because many projects include both areas. To exemplify this approach, two example projects are developed throughout the book, one focusing on hardware and the other on software. This book Presents many techniques for capturing requirements. Demonstrates gap analysis to find missing requirements. Shows how to address both software and hardware, as most projects involve both. Provides extensive examples of 'shall' statements, user stories, and use cases. Explains how to supplement or replace traditional requirement statements with user stories and use cases that work well in agile development environments  What You Will LearnUnderstand the 14 techniques for capturing all requirements.
Address software and hardware needs; because most projects involve both.
Ensure all statements meet the 16 attributes of a good requirement.
Differentiate the 19 different functional types of requirement, and the 31 non-functional types.
Write requirements properly based on extensive examples of good 'shall' statements, user stories, and use cases.
Employ modeling techniques to mitigate the imprecision of words.
Audience
Writing Requirements teaches you to write requirements the correct way. It is targeted at the requirements engineer who wants to improve and master his craft. This is also an excellent book from which to teach requirements engineering at the university level. Government organizations at all levels, from Federal to local levels, can use this book to ensure they begin all development projects correctly. As well, contractor companies supporting government development are also excellent audiences for this book.


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.

Autoren/Hrsg.

Koelsch, George

Inhaltsverzeichnis

1;Contents at a Glance;5
2;Contents;7
3;About the Author;21
4;Acknowledgments;22
5;Part I: The Foundation of Requirements;23
5.1;Chapter 1: The Importance of Requirements;24
5.1.1;Requirements Conventions Used in the Book;26
5.1.2;Projects Used in This Book;27
5.1.2.1;FBI Record Management Project;28
5.1.2.2;Radiation Dosimetry Project;28
5.1.3;Basic Definitions;29
5.1.3.1;Definitions of Requirements-Related Terms;29
5.1.3.2;How Long Does It Take Requirements Engineers to…;30
5.1.4;What Makes a Good RE?;32
5.1.4.1;Personality Traits;32
5.1.4.1.1;Patience;32
5.1.4.1.2;Clarity of Thought;33
5.1.4.1.3;Flexibility;35
5.1.4.1.4;Extrovertism;35
5.1.4.1.5;Confidence;36
5.1.4.1.6;Negative Traits;37
5.1.4.2;Good Communications Skills;38
5.1.4.2.1;Responsiveness;38
5.1.4.2.2;Translator;39
5.1.4.2.3;Moderator;39
5.1.4.2.4;Persuasiveness;40
5.1.5;Summary;40
5.1.6;Challenges for Writing Effective Requirements;40
5.1.6.1;Insufficient Requirements;40
5.1.6.2;Scope;42
5.1.6.3;Requirements Creep;43
5.1.6.4;Volatility;43
5.1.6.5;Stove-Piped Requirements;44
5.1.6.6;Users Are Not Sure What They Need;45
5.1.6.7;User Needs Not Satisfied;46
5.1.6.8;Multiple Interpretations Cause Disagreements;47
5.1.6.9;Are the Requirements Verifiable?;47
5.1.6.10;Wasted Time and Resources Building the Wrong Functions;48
5.1.7;Summary;49
5.1.8;References;50
5.1.9;Exercises;50
5.1.9.1;Exercise 1;50
5.1.9.2;Exercise 2;50
5.2;Chapter 2: What Makes a Good Requirement?;51
5.2.1;Understanding Requirements;51
5.2.1.1;The Form of a Requirement;51
5.2.1.2;Dealing with Negatives in Requirements;53
5.2.2;Attributes of a Good Requirement;54
5.2.2.1;Accurate;56
5.2.2.2;Atomic;56
5.2.2.2.1;Parent-Child Requirements;57
5.2.2.3;Complete;58
5.2.2.3.1;Completeness of an Individual Requirement;58
5.2.2.3.2;Completeness of a Group of Requirements;60
5.2.2.4;Concise;63
5.2.2.5;Consistent;64
5.2.2.6;Does Not Conflict with Other Requirements;66
5.2.2.7;Does Not Duplicate Other Requirements;67
5.2.2.8;Independent;68
5.2.2.8.1;Stand on Its Own;68
5.2.2.8.2;Implementation Independent;69
5.2.2.9;Prioritized;71
5.2.2.10;Realistic;73
5.2.2.11;Traceable;75
5.2.2.11.1;Traceability;75
5.2.2.11.2;Traced to a Source;76
5.2.2.12;Unambiguous;78
5.2.2.12.1;Ambiguity in General;78
5.2.2.12.2;Subjective Terminology;80
5.2.2.12.3;Troublesome Parts of Speech;81
5.2.2.12.4;Passive Voice;83
5.2.2.13;Understandable by Stakeholders;84
5.2.2.14;Unique;86
5.2.2.15;Verifiable;86
5.2.2.15.1;Testing;87
5.2.2.15.2;Inspection;88
5.2.2.15.3;Demonstration;88
5.2.2.15.4;Simulation;89
5.2.2.15.5;Analysis;89
5.2.2.15.6;Wrap-Up of Verifiable;90
5.2.2.16;One More Attribute: Modifiable;90
5.2.3;Capability Within a Requirement;91
5.2.4;Types of Errors That Can Occur with Requirements;91
5.2.4.1;Dangerous or Toxic Requirements;92
5.2.4.2;Extra, Superfluous Requirements;92
5.2.4.3;Incomplete Requirements;92
5.2.4.4;Others;93
5.2.5;References;93
5.2.6;Exercises;93
5.2.6.1;Exercise 1;93
5.2.6.2;Exercise 2;94
5.2.6.3;Exercise 3;94
5.2.6.4;Exercise 4;94
5.2.6.5;Exercise 5;94
5.3;Chapter 3: Specialized Language;95
5.3.1;The Use of Language;95
5.3.2;Defining Specialized Terms;97
5.3.3;Acronyms and Abbreviations;98
5.3.4;Summary;100
5.3.5;Exercises;100
5.3.5.1;Exercise 1;100
5.3.5.2;Exercise 2;100
6;Part II: Types of Requirements;101
6.1;Chapter 4: Functional Requirements;102
6.1.1;Understanding Types of Requirements;102
6.1.2;Types of Functional Requirements;103
6.1.2.1;Business Rules;104
6.1.2.2;Transactions;105
6.1.2.2.1;Transaction Entry;105
6.1.2.2.2;Transaction Change;106
6.1.2.2.3;Transaction Errors;106
6.1.2.3;Administrative Functions;107
6.1.2.4;Authentication;108
6.1.2.5;Authorization Levels;109
6.1.2.6;Audit Tracking;110
6.1.2.7;External Interfaces;111
6.1.2.8;Certification Requirements;112
6.1.2.9;Searching and Reporting Requirements;113
6.1.2.10;Compliance, Legal, or Regulatory Requirements;116
6.1.2.11;Historical Data;117
6.1.2.12;Archiving;118
6.1.2.13;Structural;119
6.1.2.14;Algorithms;120
6.1.2.15;Database;120
6.1.2.16;Power;121
6.1.2.17;Network;122
6.1.2.18;Infrastructure;122
6.1.2.19;Backup and Recovery;123
6.1.3;Summary;124
6.1.4;Exercises;124
6.1.4.1;Exercise 1;124
6.1.4.2;Exercise 2;124
6.2;Chapter 5: Nonfunctional Requirements;125
6.2.1;The Types of Nonfunctional Requirements;125
6.2.1.1;Architectural;126
6.2.1.2;Capacity;127
6.2.1.3;Constraints;128
6.2.1.4;Documentation;129
6.2.1.5;Efficiency;129
6.2.1.6;Effectiveness;130
6.2.1.7;Fault Tolerance;130
6.2.1.8;Privacy;131
6.2.1.9;Quality;131
6.2.1.10;Resilience;132
6.2.1.11;Robustness;132
6.2.1.12;Environmental;133
6.2.1.13;Data Integrity;133
6.2.1.14;Standards;133
6.2.1.15;Performance;134
6.2.1.15.1;Performance Response Time;135
6.2.1.15.2;Workload Performance;136
6.2.1.15.3;Platform Performance;137
6.2.1.15.4;Performance Profiles;137
6.2.1.15.5;Throughput;138
6.2.1.16;Reliability, Availability, and Maintainability (RAM);139
6.2.1.16.1;Definitions;139
6.2.1.16.1.1;Mean Time to Repair (MTTR);140
6.2.1.16.1.2;Wait Time;140
6.2.1.16.1.3;Mean Time Between Failures (MTBF);140
6.2.1.16.2;Availability;140
6.2.1.16.3;Maintainability;142
6.2.1.16.3.1;Mean Time to Maintain (MTTM);142
6.2.1.16.3.2;Mean Time Between Maintenance (MTBM);142
6.2.1.16.4;Reliability;144
6.2.1.16.4.1;Failure Definition;145
6.2.1.17;Security;147
6.2.1.17.1;Access Control;148
6.2.1.17.2;Import From and Export to Outside the System;149
6.2.1.17.3;Connections to Outside the System;150
6.2.1.17.4;Reuse;152
6.2.1.18;Scalability;154
6.2.1.19;Usability;157
6.2.1.20;Accessibility;158
6.2.1.21;Interoperability;159
6.2.1.22;Portability;160
6.2.1.23;Stability;161
6.2.1.24;Supportability;162
6.2.1.25;Testability;162
6.2.1.26;Recoverability;163
6.2.1.27;Serviceability;163
6.2.1.28;Manageability;164
6.2.2;Summary;164
6.2.3;References;165
6.2.4;Exercises;165
6.2.4.1;Exercise 1;165
6.2.4.2;Exercise 2;165
6.2.4.3;Exercise 3;165
6.2.4.4;Exercise 4;165
6.2.4.5;Exercise 5;166
6.2.4.6;Exercise 6;166
6.2.4.7;Exercise 7;166
6.2.4.8;Exercise 8;166
6.2.4.9;Exercise 9;167
6.2.4.10;Exercise 10;167
6.2.4.11;Exercise 11;167
6.3;Chapter 6: Lists of Items and the Order of Steps and Data Elements;168
6.3.1;Lists of Items in Requirements;168
6.3.2;Lists of Data Elements;172
6.3.2.1;Diagnostics Request;173
6.3.2.2;Diagnostics Response;174
6.3.2.3;Image Request Message;176
6.3.2.4;Image Response Message;176
6.3.3;Order of Steps in Requirements;181
6.3.4;Order of Data Elements in Requirements;183
6.3.5;Exercises;184
6.3.5.1;Exercise 1;184
6.3.5.2;Exercise 2;185
6.4;Chapter 7: Data Interfaces and Documents;186
6.4.1;Defining Requirement Data Elements;186
6.4.1.1;Defining Data Elements Within a Requirement;186
6.4.1.2;Defining Data Elements Within a Database;188
6.4.2;Interface Control Documents;191
6.4.3;Input/Outputs;194
6.4.3.1;Outputs;194
6.4.3.2;Inputs;196
6.4.3.3;Transformations;197
6.4.4;Interface Control Document Formats;198
6.4.4.1;HUD Guidelines for the Data Requirements Document Checklist;199
6.4.4.2;DoD;201
6.4.4.2.1;MIL-STD 962D (Military Standard);201
6.4.4.2.1.1;Foreword;202
6.4.4.2.2;8.4.2.2 DI-SDMP-81470 Department of Defense (DoD) Interface Standard Documents;202
6.4.4.3;NASA Training Manual for Elements of Interface Definition and Control;204
6.4.4.4;Centers for Medicare & Medicaid Services CMS eXpedited Life Cycle (XLC);209
6.4.5;References;210
6.4.6;Exercises;211
6.4.6.1;Exercise 1;211
6.4.6.2;Exercise 2;211
6.5;Chapter 8: Physical Requirements;212
6.5.1;Physical Hardware Characteristics;212
6.5.1.1;Overall Weight;213
6.5.1.2;Size;213
6.5.1.3;Geometric Shape;214
6.5.1.4;Volume;215
6.5.1.5;Density;215
6.5.1.6;Center of Gravity;215
6.5.1.7;Human Portable;216
6.5.1.8;Safety Features;216
6.5.1.9;Storage;217
6.5.1.10;Packaging, Cooling, Heating, and Integration Constraints;217
6.5.1.11;Power Consumption;218
6.5.1.12;Material;218
6.5.1.13;Surface Coefficient of Friction;219
6.5.1.14;Physical Robustness;219
6.5.1.15;Reliability;219
6.5.1.16;Throughput;219
6.5.1.17;Physical Computer Characteristics;220
6.5.2;Throughput Characteristics;221
6.5.2.1;Throughput;221
6.5.2.2;Latency;223
6.5.3;References;224
6.5.4;Exercises;224
6.5.4.1;Exercise 1;224
6.5.4.2;Exercise 2;224
7;Part III: Cradle to Grave Requirements;225
7.1;Chapter 9: How to Collect Requirements;226
7.1.1;Elicitation;227
7.1.2;Techniques of Elicitation;228
7.1.2.1;Elicitation Basics;228
7.1.2.2;Requirements Sources;228
7.1.2.2.1;Stakeholders;229
7.1.2.2.2;Documents;229
7.1.2.2.3;System in Operation;229
7.1.2.3;An Overview of Elicitation Techniques;229
7.1.2.4;Questionnaires/Surveys;231
7.1.2.5;Group Meetings;232
7.1.2.5.1;Facilitated Session;232
7.1.2.5.2;Focus Group;233
7.1.2.5.3;Joint Application Development/Requirements Workshop;233
7.1.2.5.4;Support Teams;233
7.1.2.5.5;Brainstorming;234
7.1.2.6;Interviewing;235
7.1.2.6.1;Size of Interviews Vary;235
7.1.2.6.2;In-Person, Telephone, Videoconference, and Online Interviews;236
7.1.2.6.3;Segregate by User Roles;236
7.1.2.6.4;Running an Interview;237
7.1.2.6.5;Things That Enhance the Interview;238
7.1.2.6.5.1;Listening;239
7.1.2.6.5.2;Things Change Over Time;239
7.1.2.6.5.3;Glossaries;239
7.1.2.6.5.4;Note Taking;239
7.1.2.6.5.5;Follow-Up Questions;240
7.1.2.6.5.6;Missing Knowledge;240
7.1.2.6.5.7;Cultural/Language Differences;241
7.1.2.7;Following People Around/Observation;241
7.1.2.8;Models;242
7.1.2.9;Document Analysis;242
7.1.2.9.1;Business Process;243
7.1.2.9.2;Existing Requirements;243
7.1.2.9.3;Existing Interface Documents;244
7.1.2.9.4;Design Documents;244
7.1.2.9.5;Manuals: User, Operations, Training, and Help;244
7.1.2.9.6;Identified Problems and Changes;244
7.1.2.9.7;Competing or Analogous Systems;245
7.1.2.10;Prototyping;246
7.1.2.11;Use Cases/Scenarios/User Stories;246
7.1.2.12;Working in the Target Environment;247
7.1.2.13;Request for Proposals;247
7.1.2.14;Reverse Engineering;247
7.1.2.15;Tools;248
7.1.2.16;Purpose of Elicitation;249
7.1.2.16.1;Defining the Scope of the System;249
7.1.2.16.2;Gaining Domain Knowledge;249
7.1.2.16.3;Deciding On the Elicitation Techniques to Use;250
7.1.2.16.4;Eliciting the Requirements;250
7.1.2.16.5;Performing a Gap Analysis;252
7.1.2.16.6;Completing the Requirements;252
7.1.3;Problems with Elicitation;253
7.1.3.1;Problems of Scope;254
7.1.3.1.1;The Boundary of the System Is Ill-Defined;254
7.1.3.1.2;Unnecessary Design Information May Be Given;254
7.1.3.2;Problems of Understanding;254
7.1.3.2.1;Users Have an Incomplete Understanding of Their Needs;254
7.1.3.2.2;Users Have Poor Understanding of Computer Capabilities and Limitations;255
7.1.3.2.3;Analysts Have Poor Knowledge of Problem Domain;255
7.1.3.2.4;User and Analyst Speak Different Languages;255
7.1.3.2.5;Ease of Omitting “Obvious” Information;256
7.1.3.2.6;Conflicting Views of Different Users;256
7.1.3.2.7;Requirements Are Often Vague and Untestable;256
7.1.3.3;Problems of Volatility: Requirements Evolve;256
7.1.3.3.1;Requirements Evolve Over Time;256
7.1.4;Process Improvement;256
7.1.5;References;258
7.1.6;Exercises;258
7.1.6.1;Exercise 1;258
7.1.6.2;Exercise 2;258
7.2;Chapter 10: User Interface Requirements;259
7.2.1;Introducing UI Requirements;259
7.2.2;Improving the User Interface;261
7.2.2.1;Government UI Improvements;261
7.2.2.2;Candidate UI Topics for Requirements;263
7.2.2.3;Error Conditions;264
7.2.2.4;Human Factors;265
7.2.3;Section 508 Compliance;267
7.2.4;References;268
7.2.5;Exercises;269
7.2.5.1;Exercise 1;269
7.3;Chapter 11: Managing Requirements;270
7.3.1;Why Should You Manage Requirements?;270
7.3.2;A Bit of a History Lesson;271
7.3.3;What Types of Tools Should You Consider?;272
7.3.3.1;Attributes of Effective Requirement Management Tools;273
7.3.3.2;The Tools;274
7.3.3.3;Rating of the Tools;274
7.3.3.4;Importing;277
7.3.4;What Requirement Values Should You Manage?;278
7.3.4.1;Requirements Fields;278
7.3.4.2;Requirements Associated with Testing Fields;283
7.3.4.3;Requirements Associated with Agile Fields;283
7.3.5;References;284
7.3.6;Exercises;285
7.3.6.1;Exercise 1;285
7.3.6.2;Exercise 2;285
7.3.6.3;Exercise 3;285
8;Part IV: Alternatives to Shall Requirements;286
8.1;Chapter 12: Supplementing or Replacing Standard Requirements;287
8.1.1;User Stories and Use Cases;288
8.1.1.1;User Stories;288
8.1.1.2;Use Cases;289
8.1.1.3;Supplementing Your Requirements;291
8.1.1.4;Replacements for Requirements;291
8.1.2;Modeling;292
8.1.2.1;General Modeling;293
8.1.2.2;Models for Ordinary Requirements;294
8.1.2.2.1;Swim Lanes;294
8.1.2.2.2;Data Flow Diagrams (DFDs);296
8.1.2.3;Specialized Modeling;299
8.1.2.4;Tools That Can Aid Requirements Gathering;300
8.1.2.4.1;Affinity Diagrams;300
8.1.2.4.2;Storyboarding;301
8.1.3;Other Supplements to Requirements Process;306
8.1.3.1;Off-the-Shelf Solutions;306
8.1.3.2;IEEE Standards;308
8.1.3.3;ISO 9001:2008;309
8.1.3.4;CMM/CMMI Levels of Maturity;309
8.1.3.5;INCOSE;311
8.1.4;References;311
8.2;Chapter 13: User Stories;313
8.2.1;Anatomy of a User Story;313
8.2.1.1;Parts of a User Story;313
8.2.1.2;Attributes of a User Story;315
8.2.1.2.1;Independent;316
8.2.1.2.2;Negotiable;317
8.2.1.2.3;Valuable;319
8.2.1.2.4;Estimable;320
8.2.1.2.5;Small;322
8.2.1.2.6;Testable;325
8.2.2;Acceptance Criteria;326
8.2.3;Size of stories;328
8.2.4;Complement vs. Supplement to Requirements;330
8.2.4.1;Complement to Requirements;330
8.2.4.2;Replacement for Requirements;331
8.2.5;User Stories Traceability;331
8.2.6;Maintain User Stories;334
8.2.7;What Can Go Wrong with Writing User Stories?;335
8.2.8;Summary;337
8.2.9;References;337
8.2.10;Exercises;338
8.2.10.1;Exercise 1;338
8.2.10.2;Exercise 2;338
8.2.10.3;Exercise 3;338
8.2.10.4;Exercise 4;338
8.2.10.5;Exercise 5;338
8.2.10.6;Exercise 6;338
8.3;Chapter 14: Use Cases;339
8.3.1;Writing Use Cases;339
8.3.1.1;Use Case Sequence;339
8.3.1.2;Login Use Case;341
8.3.1.3;Unit Dosimetry Report Use Case;348
8.3.1.4;Gap Analysis;352
8.3.2;Advantages and Disadvantages of Use Cases;354
8.3.2.1;Advantages;355
8.3.2.2;Disadvantages;356
8.3.3;Complement vs. Replacement to Requirements;358
8.3.3.1;Complement to Requirements;358
8.3.3.2;Replacement for Requirements;359
8.3.3.3;All Three Together;360
8.3.4;References;360
8.3.5;Exercises;360
8.3.5.1;Exercise 1;360
8.3.5.2;Exercise 2;360
8.4;Chapter 15: Revisiting Requirement Problems and Their Solutions;361
8.4.1;Insufficient Requirements;361
8.4.2;Requirements Creep;362
8.4.3;Volatility;362
8.4.4;Stove-Piped Requirements;363
8.4.5;Scope: Boundaries Can Be Ill-Defined;363
8.4.6;Understanding Users Are Not Sure What They Need;364
8.4.7;May Not Satisfy User Needs;365
8.4.8;Misinterpretation: Cause Disagreements;365
8.4.9;Cannot Verify the Requirements;366
8.4.10;Wasted Time and Resources Building the Wrong Functions;367
8.4.11;Summary;367
8.4.12;Exercises;368
8.4.12.1;Exercise 1:;368
8.4.12.2;Exercise 2:;368
8.4.12.3;Exercise 3:;368
9;Part V: Appendixes;369
9.1;Appendix A: Acronyms and Abbreviations;370
9.2;Appendix B: Requirements Documents;375
9.2.1;DoD FRD Template;375
9.2.1.1;FUNCTIONAL REQUIREMENTS DOCUMENT (FRD) FOR DEPARTMENT OF DEFENSE (DOD) ;376
9.2.1.2;Comments on This DoD FRD;377
9.2.2;IEEE Document Formats;377
9.2.3;Final Comments on Requirements Document Formats;377
9.2.4;References;378
9.3;Appendix C: Section 508 Compliance;379
9.3.1;The Background for Section 508;379
9.3.1.1;Background;379
9.3.2;Exemptions to Section 508;380
9.3.2.1;Section 1194.3 General Exceptions;380
9.3.3;Section 508 Technical Standards;380
9.3.3.1;Subpart B – Technical Standards;380
9.3.3.1.1;§ 1194.21 Software Applications and Operating Systems;380
9.3.3.1.2;§ 1194.22 Web-based Intranet and Internet Information and Applications;381
9.3.3.1.3;§ 1194.23 Telecommunications Products;383
9.3.3.1.4;§ 1194.24 Video and Multimedia Products;384
9.3.3.1.5;§ 1194.25 Self-contained, Closed Products;385
9.3.3.1.6;§ 1194.26 Desktop and Portable Computers;386
9.3.4;Section 508 Functional Performance Criteria;387
9.3.4.1;Subpart C – Functional Performance Criteria;387
9.3.4.1.1;§ 1194.31 Functional Performance Criteria;387
9.3.5;Section 508 Information, Documentation, and Support;387
9.3.5.1;Subpart D – Information, Documentation, and Support;388
9.3.5.1.1;§ 1194.41 Information, Documentation, and Support;388
9.4;Glossary;389
9.5;Bibliography;398
10;Index;402