Hardware and Software Projects Troubleshooting: How Effective Requirements Writing Can Save the Day, 2nd Edition

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 modelling 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 performed during his career. More importantly, you will learn how these techniques can prevent the problems that occur during requirements development. Most of all, you will learn how good requirements governance will greatly increase the success of development projects by getting all people involved to eliminate the adverse impacts to requirements throughout the development lifecycle. Hardware and Software Projects Troubleshooting covers techniques for defining user needs, so you can determine which combination of approaches to use for your projects. You’ll also learn how to analyze the different development methodologies so that you can determine the advantages and disadvantages of different requirements approaches and implement them correctly as your needs evolve. Unlike most requirements books, this one 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. What You Will Learn Focus on how to eliminate or mitigate requirements problems Understand 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 requirements, and the 31 non-functional types Write requirements properly based on extensive examples of good ‘shall’ statements, user stories, and use cases Employ modelling techniques to mitigate the imprecision of words Install requirements governance to significantly improve project success Who This Book Is For Requirements engineers who want to improve and master their craft, as well as students and those employed in government or other organizations at all levels. Table of Contents About the Author Acknowledgments Introduction Part I: The Foundation of Requirements Chapter 1: The Importance of Requirements Requirements Conventions Used in the Book Projects Used in This Book FBI Records Management Project Radiation Dosimetry Project Basic Definitions Definitions of Requirements-Related Terms How Long Does It Take Requirements Engineers to ... What Makes a Good RE? Personality Traits Patience Clarity of Thought Flexibility Extrovertism Confidence Negative Traits Good Communication Skills Responsiveness Translator Moderator Persuasiveness Summary Challenges for Writing Effective Requirements Insufficient Requirements Scope Requirements Creep Volatility Stove-Piped Requirements Requirements Do Not Reflect What Users/Stakeholders Need User Needs Not Satisfied Multiple Interpretations Cause Disagreements Are the Requirements Verifiable? Wasted Time and Resources Building the Wrong Functions Adversely Impacts the Schedule Adversely Impacts Communication with Users/Stakeholders or Development/Test Team Priorities Are Not Adequately Addressed Summary References Exercises Exercise 1 Exercise 2 Chapter 2: What Makes a Good Requirement? Understanding Requirements The Form of a Requirement Dealing with Negatives in Requirements Attributes of a Good Requirement Accurate Atomic Parent-Child Requirements Complete Completeness of an Individual Requirement Completeness of a Group of Requirements Concise Consistent Does Not Conflict with Other Requirements Does Not Duplicate Other Requirements Independent Stands on Its Own Implementation Independent Prioritized Realistic Traceable Traceability Traced to a Source Unambiguous Ambiguity in General Subjective Terminology Troublesome Parts of Speech Passive Voice Understandable by Stakeholders Unique Verifiable Testing Inspection Demonstration Simulation Analysis Wrap-Up of Verifiable One More Attribute: Modifiable Capability Within a Requirement Types of Errors That Can Occur with Requirements Dangerous or Toxic Requirements Extra, Superfluous Requirements Incomplete Requirements Others Approach for Evaluating Requirement Problems Summary/Review of Requirement Problems Based on Chapter 2 Tools Tools in Chapter 2 Requirement Problems Insufficient Requirements Requirements Creep Volatility Stove-Piped Requirements Scope: Boundaries Can Be Ill-Defined Understanding Users Are Not Sure What They Need Do Not Reflect What Users/Stakeholders Need Misinterpretation: Causes Disagreements Cannot Verify the Requirements Wasted Time and Resources Building the Wrong Functions Adversely Impacts the Schedule Adversely Impacts Communication with Users/Stakeholders or Development/Test Team Priorities Are Not Adequately Addressed References Exercises Exercise 1 Exercise 2 Exercise 3 Exercise 4 Chapter 3: Specialized Language The Use of Language Defining Specialized Terms Acronyms and Abbreviations Summary/Review of Requirement Problems Based on Chapter 3 Tools Tools in Chapter 3 Requirement Problems Exercises Exercise 1 Exercise 2 Part II: Types of Requirements Chapter 4: Functional Requirements Understanding Types of Requirements Types of Functional Requirements Business Rules Transactions Transaction Entry Transaction Change Transaction Errors Administrative Functions Authentication Authorization Levels Audit Tracking External Interfaces Certification Requirements Searching and Reporting Requirements Compliance, Legal, or Regulatory Requirements Historical Data Archiving Structural Algorithms Database Power Network Infrastructure Backup and Recovery Summary/Review of Requirement Problems Based on Chapter 4 Tools Tools in Chapter 4 Requirement Problems Exercises Exercise 1 Exercise 2 Chapter 5: Nonfunctional Requirements The Types of Nonfunctional Requirements Architectural Capacity Constraints Documentation Efficiency Effectiveness Fault Tolerance Privacy Quality Resilience Robustness Environmental Data Integrity Standards Performance Response Time Performance Workload Performance Platform Performance Performance Profiles Throughput Reliability, Availability, and Maintainability (RAM) Definitions Mean Time to Repair (MTTR) Wait Time Mean Time Between Failures (MTBF) Availability Maintainability Mean Time to Maintain (MTTM) Mean Time Between Maintenance (MTBM) Reliability Failure Definition Security Access Control Import From and Export to Outside the System Connections to Outside the System Reuse Scalability Usability Accessibility Interoperability Portability Stability Supportability Testability Recoverability Serviceability Manageability Summary/Review of Requirement Problems Based on Chapter 5 Tools Tools in Chapter 5 Requirement Problems References Exercises Exercise 1 Exercise 2 Exercise 3 Exercise 4 Exercise 5 Exercise 6 Exercise 7 Exercise 8 Exercise 9 Exercise 10 Exercise 11 Chapter 6: Lists of Items and the Order of Steps and Data Elements Lists of Items in Requirements Lists of Data Elements Diagnostics Request Diagnostics Response Image Request Message Image Response Message Order of Steps in Requirements Order of Data Elements in Requirements Summary/Review of Requirement Problems Based on Chapter 6 Tools Tools in Chapter 6 Requirement Problems Exercises Exercise 1 Exercise 2 Chapter 7: Data Interfaces and Documents Defining Requirements Data Elements Defining Data Elements Within a Requirement Defining Data Elements Within a Database Interface Control Documents Inputs/Outputs Outputs Inputs Transformations Interface Control Document Formats Housing and Urban Development (HUD) Guidelines for the Data Requirements Document Checklist DoD MIL-STD 962D (Military Standard) Foreword 8.4.2.2 DI-SDMP-81470 Department of Defense (DoD) Interface Standard Documents NASA Training Manual for Elements of Interface Definition and Control Centers for Medicare & Medicaid Services (CMS) eXpedited Life Cycle (XLC) Summary/Review of Requirement Problems Based on Chapter 7 Tools Tools in Chapter 7 Requirement Problems References Exercises Exercise 1 Exercise 2 Chapter 8: Physical Requirements Physical Hardware Characteristics Overall Weight Size Geometric Shape Volume Density Center of Gravity Human Portable Safety Features Storage Packaging, Cooling, Heating, and Integration Constraints Power Consumption Material Surface Coefficient of Friction Physical Robustness Reliability Throughput Physical Computer Characteristics Throughput Characteristics Throughput Latency Summary/Review of Requirement Problems Based on Chapter 8 Tools Tools in Chapter 8 Requirement Problems References Exercises Exercise 1 Exercise 2 Part III: Cradle to Grave Requirements Chapter 9: How to Collect Requirements Elicitation Techniques of Elicitation Elicitation Basics Requirements Sources Stakeholders Documents System in Operation An Overview of Elicitation Techniques Questionnaires/Surveys Group Meetings Facilitated Session Focus Group Joint Application Development/Requirements Workshop Support Teams Brainstorming Interviewing Size of Interviews Vary In-Person, Telephone, Videoconference, and Online Interviews Segregate by User Roles Running an Interview Things That Enhance the Interview Listening Things Change Over Time Glossaries Note Taking Follow-Up Questions Missing Knowledge Cultural/Language Differences Following People Around/Observation Models Document Analysis Business Process Existing Requirements Existing Interface Documents Design Documents Manuals: User, Operations, Training, and Help Identified Problems and Changes Competing or Analogous Systems Prototyping Use Cases/Scenarios/User Stories Working in the Target Environment Request for Proposals (RFP) Reverse Engineering Tools Purpose of Elicitation Defining the Scope of the System Gaining Domain Knowledge Deciding on the Elicitation Techniques to Use Eliciting the Requirements Performing a Gap Analysis Completing the Requirements Problems with Elicitation Problems of Scope The Boundary of the System Is Ill-Defined Unnecessary Design Information May Be Given Problems of Understanding Users Have an Incomplete Understanding of Their Needs Users Have a Poor Understanding of Computer Capabilities and Limitations Analysts Have Poor Knowledge of Problem Domain User and Analyst Speak Different Languages It’s Easy to Omit “Obvious” Information Different Users Have Different Views Requirements Are Often Vague and Untestable Problems of Volatility: Requirements Evolve Requirements Evolve Over Time Process Improvement Summary/Review of Requirement Problems Based on Chapter 9 Tools Tools in Chapter 9 Requirement Problems References Exercises Exercise 1 Exercise 2 Chapter 10: User Interface Requirements Introducing UI Requirements Improving the User Interface Government UI Improvements Candidate UI Topics for Requirements Error Conditions Human Factors Section 508 Compliance Summary/Review of Requirement Problems Based on Chapter 10 Tools Tools in Chapter 10 Requirement Problems References Exercises Exercise 1 Chapter 11: Managing Requirements Why Should You Manage Requirements? A Bit of a History Lesson What Types of Tools Should You Consider? Attributes of Effective Requirements Management Tools The Tools First Evaluation Rating of the Tools Importing Second Evaluation What Requirement Values Should You Manage? Requirements Fields Requirements Associated with Testing Fields Requirements Associated with Agile Fields Summary/Review of Requirement Problems Based on Chapter 11 Tools Tools in Chapter 11 Requirement Problems References Exercises Exercise 1 Exercise 2 Exercise 3 Part IV: Alternatives to Shall Requirements Chapter 12: Supplementing or Replacing Standard Requirements User Stories and Use Cases User Stories Use Cases Supplementing Your Requirements Replacements for Requirements Modeling General Modeling Models for Ordinary Requirements Swim Lanes Data Flow Diagrams (DFDs) Specialized Modeling Tools That Can Aid Requirements Gathering Affinity Diagrams Storyboarding Other Supplements to Requirements Process Off-the-Shelf Solutions IEEE Standards ISO 9001:2008 CMM/CMMI Levels of Maturity INCOSE Summary/Review of Requirement Problems Based on Chapter 12 Tools Tools in Chapter 12 Requirement Problems References Chapter 13: User Stories Anatomy of a User Story Parts of a User Story Attributes of a User Story Independent Negotiable Valuable Estimable Small Testable Acceptance Criteria Size of Stories Complement vs. Supplement to Requirements Complement to Requirements Replacement for Requirements User Stories Traceability Maintain User Stories What Can Go Wrong with Writing User Stories? Summary/Review of Requirement Problems Based on Chapter 13 Tools Tools in Chapter 13 Requirement Problems Summary References Exercises Exercise 1 Exercise 2 Exercise 3 Exercise 4 Exercise 5 Exercise 6 Chapter 14: Use Cases Writing Use Cases Use Case Sequence Login Use Case Unit Dosimetry Report Use Case Gap Analysis Advantages and Disadvantages of Use Cases Advantages Disadvantages Complement vs. Replacement to Requirements Complement to Requirements Replacement for Requirements All Three Together Summary/Review of Requirement Problems Based on Chapter 14 Tools Tools in Chapter 14 Requirement Problems References Exercises Exercise 1 Exercise 2 Part V: Focus on Requirements Problems Chapter 15: The Proper Way to Define Requirements Governance Introduction to Requirements Governance Problems with Not Doing Requirements Well Detail of Each Requirement Problem Listed Earlier Insufficient Requirements Requirements Creep Volatility Stove-Piped Requirements Scope Users Not Sure What They Need Requirements Do Not Reflect What Users/Stakeholders Need Interpretation: Causes Disagreements Cannot Verify the Requirements Wasted Time and Resources Building the Wrong Functions Adversely Impacts the Schedule Adversely Impacts Communication with Users/Stakeholders or Development/Test Team Priorities Are Not Adequately Addressed Summary Analysis of a Governance Item Requirements Governance Template Example 1 Example 2 Scoring for Each Governance Item Action to Take An Additional Requirements Process to Consider Summary/Review of Requirement Problems Based on Requirements Governance Insufficient Requirements Requirements Creep Volatility Stove-Piped Requirements Scope—Boundaries Can Be Ill-Defined Understanding Users Are Not Sure What They Need May Not Satisfy User Needs Misinterpretation: Causes Disagreements Cannot Verify the Requirements Wasted Time and Resources Building the Wrong Functions Adversely Impacts the Schedule Adversely Impacts Communication with Users/Stakeholders or Development/Test Team Priorities Are Not Adequately Addressed Exercises Exercise 1 Chapter 16: Revisiting Requirement Problems and Their Solutions Recap of List of Requirements Problems Final Analysis of Problem Reports Insufficient Requirements Evaluation Conclusions Requirements Creep Evaluation Conclusions Volatility Evaluation Conclusions Stove-Piped Requirements Evaluation Conclusions Scope: Boundaries Can Be Ill-Defined Evaluation Conclusions Understanding Users Are Not Sure What They Need Evaluation Conclusions May Not Satisfy User Needs Evaluation Conclusions Misinterpretation: Causes Disagreements Evaluation Conclusions Cannot Verify the Requirements Evaluation Conclusions Wasted Time and Resources Building the Wrong Functions Evaluation Conclusion Adversely Impacts the Schedule Evaluation Conclusion Adversely Impacts Communication with Users/Stakeholders or Development/Test Team Evaluation Conclusion Priorities Are Not Adequately Addressed Evaluation Conclusion Summary Exercises Exercise 1 Exercise 2 Exercise 3 Part VI: Appendixes Appendix A: Acronyms and Abbreviations Appendix B: Requirements Documents DoD FRD Template FUNCTIONAL REQUIREMENTS DOCUMENT (FRD) FOR DEPARTMENT OF DEFENSE (DOD) Comments on This DoD FRD IEEE Document Formats Final Comments on Requirements Document Formats References Appendix C: Section 508 Compliance Our Mission Design & Develop: Design and Develop Accessible Products Summary Glossary Bibliography Index