Writing Objectives and Requirements

1. Writing Objectives and Requirements

2. CONTENTS • Module 1: Different Kinds of Requirements • Module 2: Characteristics of Good Requirements • Module 3: Requirements Writing Tips • Module 4: Practice Exercises • Module 5: Back to Our Case Study • Appendix: The Inherent Difficulty of Requirements

3. MODULE 1 Different Kinds of Requirements

4. What are Requirements? “Requirements are … a specification of what should be implemented. They are descriptions of how the system should behave, or of a system property or attribute. They may also include constraints on the development process of the system.” [Sommerville and Sawyer, 1997]

5. Different Types of Requirements Business Requirements User Requirements Functional Requirements Business Rules Quality Attributes External Interfaces Design & Implementation Constraints System Requirements Specification [Adapted from K. Wiegers, More about Software Requirements] 5

6. Business Requirements Business requirements capture the business need and rationale for the proposed project. Business requirements tells us why-- at the business level -- we’re doing the project. They should state, or at least contain implicitly, the benefits the sponsoring business organization expects to derive from a successful project. Example: The new InvestNow equity management system will better serve our low-end equity investors (those with portfolios under $50K) by allowing them to manage their own equity portfolios online. This self-service system will provide more timely service to these investors and also save the company money through the reduction of staff currently required to manage these accounts. 6

7. User Requirements User requirements capture what the user will be able to do and accomplish with the finished product. These requirements are defined by the goals and tasks that the users must be able to perform using the product. User requirements are driven by the business requirements. In other words, if the user requirements are satisfied, this should ensure the attainment of the business requirements. Example: Users of the InvestNow equity management system will be able to 1) view their portfolio, 2) manage their account profile, 3) receive on-screen information about companies they currently invest in, 4) receive on-screen information about companies they are considering making investments in, and 5) buy and sell shares of stock within the limits set by their account profile. 7

8. Functional Requirements Functional requirements describe what the developer is supposed to build. Functional requirements specify what the system will do or what it will allow the user to do. These requirements are driven by the business and user requirements, but they go a step further by describing what the system will do to satisfy those higher-level requirements. Example: The system will allow the user to request to view his or her account profile. Upon this request, the system will display the current profile. The user will then be allowed to edit any user-editable fields in the profile. The edited profile will then be presented to the user for approval before the changes are actually made to the stored profile. etc. … 8

9. Business Rules Business rules include corporate policies, government regulations, industry standards, and specified computational methods. Business rules typically have an existence outside the specific boundaries of individual software projects and could be considered enterprise-level assets. Business rules are not software requirements per se, but they often require software elementsto ensure that the system complies with these rules. Examples: Only those customers whose total portfolio value is less than or equal to $50,000 will be allowed to utilize the InvestNow system. Investments made using InvestNow that would push the portfolio value beyond $50,000 are not allowed. Commissions on trades made within InvestNow are to be calculated utilizing the company’s ComRate25 commission table. 9

10. Quality Attributes Quality attributes describe the product’s characteristics in ways that are important to users, developers, or those who will maintain the system. Such characteristics might involve availability, performance, usability, robustness, reliability, and similar attributes. Quality attributes should be stated precisely and succinctly and where possible they should be quantified. Examples: For user editing of account profiles, drop-down menus, radio buttons and similar methods should be used where possible to make editing more convenient and to reduce user input errors. A user request to view his or her portfolio summary should be satisfied in less than 5 seconds. 10

11. External/Internal Interfaces Interfaces between the proposed system and other existing systems (hardware or software) or the external world should be specified. When human user interfaces are a part of the proposed system, these should be specified where possible using prototypes that have been approved by the appropriate human user representatives. Examples: All account profile information will continue to reside within the existing SI_Accounts DB2 database. All requests from users for investment company information will be satisfied by accessing the Investor_Inform service to which the company subscribes. The basic forms of the graphical user interfaces for the system are specified in Prototype IN101v4. 11

12. Design and Implementation Constraints Design and implementation constraints are restrictions imposed on the proposed system for some legitimate reason. These constraints might include technical features, tools to be used, languages to be used, development standards, and so on. Examples: To access the SI_Accounts database, the system will utilize the existing DB2 access modules: IN_ACC#233v1 and OUT_ACC#765v8. Any changes to the SI_Accounts database must be approved by the DBA and the Chief Design Architect. Current organizational standards require that all coding for the InvestNow system will be done in the Java programming language unless explicit permission to do otherwise is obtained from the Chief Design Architect. 12

13. Relationships Among Types of Requirements Business Requirements Business Rules Quality Attributes User Requirements External/Internal Interfaces Functional Requirements Design and Implementation Constraints System Requirements Specification 13

14. Relationships Among Types of Requirements Business Requirements Business Rules Quality Attributes User Requirements External/Internal Interfaces Functional Requirements Design and Implementation Constraints Systems Analysis System Requirements Specification (Scope Document) 14

15. Goals, Objectives and Requirements A project comes into existence to do something: to have the end result - effect some change. This is nearly always expressed in the language of the sponsor's business. For example, the result of a web development project might be to increase sales or to implement customer self-service. We call these Project Goals, and meeting these goals is the primary focus of the project sponsor. Project goals capture the intended fulfillment of a stated business need. The project exists to produce accomplishments that do fulfill the stated goals. These accomplishments, which should be measurable, we typically call Project Objectives. These are the things that the project directly produces: an eCommerce site; a web-enabled self-service application, etc. Accomplishing the project objectives should ensure that the project fulfills the stated goals. So what are Requirements? Requirements are the necessary specific outcomes that are required to realize the objectives - and that the project therefore must deliver. To put it another way, requirements are the detailed view of the project objectives. Because requirements are the things that the project must deliver, they are the absolute definition of whether the project has achieved its objectives (and thus fulfilled its goals). 15 Adapted from Introducing Project Requirements, by Martin Burns, www.evolt.org.

16. Project Objectives Project objectives are generally created at a higher level than the actual project business requirements. Objectives are usually written first, and then refined into the actual business requirements. Objectives are then in a sense just high-level requirements, and thus they must be constructed with the same care and attention to detail as the business requirements themselves. In the Modules that follow then, most of what we say about requirements will also apply to objectives. The main difference is that the business requirements, being much more detailed, will require even closer and more careful scrutiny at a detailed level than objectives. The following modified diagram captures this relationship between objectives and requirements. 16

17. Project Objectives drive High-level Business Goals/Needs refined by Business Requirements Business Rules Quality Attributes User Requirements External/Internal Interfaces Functional Requirements Design and Implementation Constraints System Requirements Specification 17

18. MODULE 2 Characteristics of Good Requirements

19. The Requirements Analysis Process Reviewed The Foundation for the Entire Project Problem Business Requirements Fuzzy Ambiguous Ill-defined Unstable System Requirements Problem Defined Solution Envisioned Business Outcomes Articulated Rigorous Precise Unambiguous Foundation for Design

20. Setting the Right Foundation • Many software requirements documents are filled with badly written requirements. • Because the quality of any product depends on the quality of the raw materials fed into it, poorly written requirements are unlikely to lead to excellent software. • In this Class/Workshop we will explore what constitutes a good set of requirements and consider some best practices for writing just that.

21. What Makes a Good Requirement? • How can we distinguish a good requirement from those that have problems? • Wiegers and others have identified five basic characteristics individual requirement statements should exhibit. • Each requirement should be: • Correct • Feasible • Necessary • Unambiguous • Verifiable (Testable) Much of the material in this Module is adapted from the article Writing Quality Requirements by Karl Wiegers published in Software Development, May 1999.

22. Each Requirement Should Be Correct • Each requirement must accurately describe the functionality to be delivered. • The checkpoint for correctness is the source of the requirement -- the actual customer. • Only the customers can determine the correctness of functional requirements, which is why it is essential to include them in the development of the requirements. • Requirements inspections that do not involve customers can lead to developers saying, "That doesn’t make sense. This is probably what they meant.“ Not a good outcome.

23. Each Requirement Should Be Feasible • It must be possible to implement each requirement within the known capabilities and limitations of the system and its environment. • To avoid infeasible requirements, someone knowledgeable about the system capabilities should work with the requirements analysts in the requirements development process. • Such a person can provide a reality check on what can and cannot be done technically, as well as to what can be done only at excessive cost or other tradeoffs.

24. Each Requirement Should Be Necessary • Each requirement should document something the customers really need or something that is required for conformance to an external requirement, an external interface, or a standard. • Another way to think of "necessary" is that each requirement originated from a source you recognize as having the authority to specify requirements. • If you cannot identify the origin and verify the authority behind the requirement, it may be an example of unnecessary "gold plating".

25. Each Requirement Should Be Unambiguous • The reader of a requirement should be able to draw only one interpretation from it. • In addition, multiple readers of a requirement should arrive at the same interpretation. • Natural languages like English are highly prone to ambiguity. • To help avoid ambiguity, we should avoid subjective words like user-friendly, easy, simple, fast, efficient, several, state-of-the-art, world-class, improved, maximized, and minimized. • We should strive to write each requirement in succinct, simple, straightforward language of the customer domain, not in computerese.

26. Each Requirement Should Be Verifiable/Testable • For each requirement you should be able to devise tests or use other verification approaches, such as inspection or demonstration, that will clearly determine whether or not each requirement is properly implemented in the product. • If a requirement is not verifiable, determining whether it was correctly implemented will become a matter of opinion and no doubt contention, leading to an unhappy implementation.

27. What Makes a Good Requirements Document? • On the previous slides we identified five characteristics that each individual requirement should have. • There are also characteristics that the set of requirements (captured in the requirements document) should possess. • A Requirements Document should be: • Complete • Consistent • Modifiable • Traceable

28. A Requirements Document Should Be Complete • No requirements or necessary information should be missing. • Note that it is hard to spot missing requirements because they aren’t there. • To help with this it is very important to organize the requirements hierarchically to help reviewers of the requirements document understand the structure of the functionality described, so it will be easier for them to tell if something is missing. • If you focus on user tasks rather than on system functions during requirements development, you are less likely both to overlook requirements and to include unnecessary requirements. • The Use Case method we described in an earlier course works well for this purpose. • If you know you are lacking certain information, use "TBD" ("to be determined") as a standard flag to highlight such gaps. All TBDs should be resolved before you proceed with construction of the relevant part of the product.

29. A Requirements Document Should Be Consistent • A consistent requirements document contains a set of requirements that do not conflict with one another or other software requirements. • Disagreements among requirements must be resolved before development can proceed. • When you find inconsistent requirements, you may not know which (if any) is correct until you do some research. • Caution: Be very careful when modifying the requirements document, because inconsistencies can slip in undetected if you review only the specific change and not any related requirements (the equivalent of regression testing for system changes).

30. A Requirements Document Should Be Modifiable • As we will see shortly, change in requirements documents is inevitable. • Thus, you must be able to revise the requirements document when necessary and maintain a history of changes made to each requirement. • This means that each requirement must be uniquely labeled and expressed separately from other requirements so you can refer to it unambiguously. • You can make a requirements document more modifiable by organizing it so that related requirements are grouped together, and by creating a table of contents, index, and cross-reference listing.

31. A Requirements Document Should Be Traceable • Each requirement in the requirements document should be linkable (traceable) to its source. • Each requirement should also be linked to the design elements, source code, and test cases that are constructed to implement and verify the requirement as the project progresses. • Traceable requirements must be uniquely labeled and written in a detailed and structured way, as opposed to large, narrative paragraphs or bullet lists.

32. MODULE 3 Requirements Writing Tips

33. The Requirements “Problem”

34. Success Rate for IT Projects 1994 CHAOS Report, Standish Group survey of 360 IT Executives representing over 8,000 projects. • Project is a success: The project is completed on-time and on-budget, with all features and functions as initially specified. • Project is challenged: The project is completed and operational, but over-budget, over the time estimate, or offers fewer features and functions than originally specified. • Project a failure: The project is canceled at some point during the development cycle.

35. Success Rate for IT Projects – Some Progress Standish Group surveys (2002 survey represents over 40,000 projects)

36. What Challenges IT Projects? • When the original Standish Group survey asked each executive IT manager to identify the most important factor that caused projects to be challenged (over budget or schedule, or both), the top three factors listed were: • 1. Lack of user input 13% • 2. Incomplete requirements 12% • 3. Changing requirements 12%

37. What Challenges IT Projects? (cont’d) • The Standish Group survey isn’t the only study to show the critical role of requirements in software development • The European Software Process Improvement Training Initiative (ESPITI) conducted a survey in which respondents were asked to identify the relative importance (major, minor, or not a problem) of various types of issues in the software process • The ESPITI survey, based on almost 4,000 responses, revealed the top two factorscited as major problems were: • 1. Requirement specifications 50% cited as a major problem • 2. Managing requirements 42% cited as a major problem

38. The Critical Importance of Good Requirements: An Example • In 2004, the FBI’s planned new automated case management system was abandoned after $170 million had been spent on its development! • One of the authors of the U.S. General Accounting Office (GAO) report on the failed project summarized its difficulties as follows (underlining added): It was a classic case of not getting the requirements sufficiently defined in terms of completeness and correctness from the beginning. And so it required a continuous redefinition of requirements that had a cascading effect on what had already been designed and produced. [From Goldstein, 2005]

39. Writing is an Art, Not a Science • There is no algorithmic way to write excellent requirements. It is largely a matter of experience and learning from the requirements problems you have encountered in the past. • On the following slides are a few guidelines to keep in mind as you document software requirements. Much of the material in this Module is adapted from the article Writing Quality Requirements by Karl Wiegers published in Software Development, May 1999.

40. Some Requirements Writing Guidelines • Write complete sentences. • Keep sentences and paragraphs short. • Use the active voice. • Use proper grammar, spelling, and punctuation. • Use terms consistently and define them in a glossary or data dictionary.

41. Some Requirements Writing Guidelines (cont’d) • To see if a requirement statement is sufficiently well defined, read it from the test designer’s and system analyst’s perspective. • Ask if you need additional clarification from the requirements author to understand the requirement well enough to test it? • If so, that requirement should be elaborated before proceeding.

42. Some Requirements Writing Guidelines (cont’d) • Requirement authors often struggle to find the right level of granularity. Avoid long narrative paragraphs that contain multiple requirements. • A helpful granularity guideline is to write individually testable requirements. If you can think of a small number of related tests to verify correct implementation of a requirement, it is probably written at the right level of detail. • If you envision many different kinds of tests, perhaps several requirements have been lumped together and should be separated.

43. Some Requirements Writing Guidelines (cont’d) • Watch out for multiple requirements that have been aggregated into a single statement. • Conjunctions like "and" and "or" in a requirement suggest that several requirements have been combined. • Never use "and/or" in a requirement statement. In other words, “A and/or B” should be replaced with “A or B, or both”.

44. Some Requirements Writing Guidelines (cont’d) • Write requirements at a consistent level of detail throughout the document. Here’s an example of such inconsistency. Suppose these two requirements were found in the same requirements document. • "A valid color code shall be R for red" and "A valid color code shall be G for green" have been split out as separate requirements (VERY DETAILED) • While in the same document you find: "The product shall respond to editing directives entered by voice" meant to describe an entire subsystem, not a single functional requirement. (VERY HIGH-LEVEL)

45. Some Requirements Writing Guidelines (cont’d) • Avoid stating requirements redundantly in the requirements document. • While including the same requirement in multiple places may make the document easier to read, it also makes maintenance of the document a nightmare. • The multiple instances of the requirement all have to be updated at the same time to prevent an inconsistency creeping in. • If you must have multiple references to the same requirement, write it once, and refer to it by number or name.

46. Writing is More Art Than Science • While there is no silver bullet, your requirements will improve drastically if you will: • Observe the guidelines given here. • Review the requirements formally, informally, early, and often. • Involve customers in a meaningful requirements partnership. • Consult testers and developers as needed for feasibility as well as clarity.

47. Walkthroughs: Validating Requirements • Before proceeding to design, it is crucial to validate: • That the requirements are correct and complete • That the requirements are testable • That you understand the relevant quality and performance attributes • That you understand implementation priorities • That all customer needs have been addressed • This is typically done using walkthroughs

48. MODULE 4 Practice Exercises

49. Example #1 • In your group analyze the following requirement, taken from an actual requirement document, against the five characteristics of a good requirement (listed below for reference). "The product shall provide status messages at regular intervals not less than every 60 seconds." Each requirement should be: * Correct * Feasible * Necessary * Unambiguous * Verifiable The material in this Module is adapted from the article Writing Quality Requirements by Karl Wiegers published in Software Development, May 1999.

50. Example #1: Possible Resolution "The product shall provide status messages at regular intervals not less than every 60 seconds." • This requirement is incomplete: what are the status messages and how are they supposed to be displayed to the user? • The requirement contains several ambiguities. What part of "the product" are we talking about? Is the interval between status messages really supposed to be at least 60 seconds, so showing a new message every 10 years is okay? Perhaps the intent is to have no more than 60 seconds elapse between messages; would 1 millisecond be too short? The word "every" just confuses the issue. • As a result of these problems, the requirement is not verifiable.