Writing Requirements Document PDF

Writing Requirement Document  Types of Requirements 1. User Requirements: are statements in natural language plus diagram of what services the system is expected to provided and constraint under which it must operate. 2. System Requirements: the set of system’s functions, services and...

Writing Requirement Document  Types of Requirements 1. User Requirements: are statements in natural language plus diagram of what services the system is expected to provided and constraint under which it must operate. 2. System Requirements: the set of system’s functions, services and operational constraints in detail. System requirements document (functional specification) should be precise and it should define exactly what is to be implemented. 3. Software specification: a detailed software description which can serve as basis for design or implementation. It is written for developers. 2  Types of Requirements Requirement Readers Client managers System end-users User requirements Client engineers Contractor managers System architects System end-users Client engineers System requirements System architects Software developers Client engineers (perhaps) Software design System architects specification Software developers 3  Software Requirements Specifications (SRS) Document SRS is the output of requirements analysis SRS should be consistence, correct, unambiguous and complete It is not a design document, it describes what system should do rather than how to do it. It contains only functional and non- functional requirement only. It does not contain suggestions, possible solutions or any information rather than the understanding of developers of customers’ needs. 4  Problems without SRS Document 1. Without developing the SRS document, the system would not be implemented according to customer needs. 2. ƒSoftware developers would not know whether what they are developing is what exactly required by the customer. 3. ƒWithout SRS document, it will be very much difficult for the maintenance engineers to understand the functionality of the system. 4. ƒIt will be very much difficult for user document writers to write the users’ manuals properly without understanding the SRS document. 5  Goals of SRS document 1. Feedback to Customers: it is the customers assurance that the developers understand the problems to be solved. SRS should be written in a natural language, and include charts, data flow diagrams, decision tables etc. 2. Problem Decomposition: SRS document divides the problem into component parts. This places borders around the problem, solidifies ideas, and help breakdown the problem into its component parts in a orderly fashion. 6  Goals of SRS document 3. Input to Design Specification: SRS serves as the parent document subsequent documents such as the software design specification and statement of work. SRS should contain sufficient delis in the functional system requirements so that a design solution should be made. 4. Production Validation Check: SRS acts as the parent document for testing and validation strategies 7  Who Writes SRS Documents Usually the system architects and programmers writes SRS documents. Requirements gathering team consist of programmers, product marketers, system analysis/architects and project managers. 8  Properties of Good SRS Document 1. Concise: The SRS document should be concise and at the same time unambiguous, consistent, and complete. 2. ƒStructured: A well-structured document is easy to understand and modify. in order to make the modifications to the SRS document easy, it is important to make the document well-structured. 3. ƒBlack-box view: It should only specify what the system should do and not stating how to do these. This means that the SRS document should specify the external behavior of the system and not discuss the implementation issues. 9  Properties of Good SRS Document 4. ƒConceptual integrity: It should show conceptual integrity so that the reader can easily understand it. 5. responses to undesired events: It should characterize acceptable responses to undesired events These are called system response to exceptional conditions. 6. ƒVerifiable: All requirements of the system as documented in the SRS document should be verifiable. This means that it should be possible to determine whether or not requirements have been met in an implementation. 10  Parts of SRS Document The important parts of SRS document are: Functional Requirements. Non-Functional Requirements. Goals of Implementation. 11  IEEE Std 830-1998 IEEE Recommended Practice for Software Requirements Specifications. This standard provides guidelines for preparing SRS documents. It covers the following aspects of an SRS 12 SRS table of contents example Table of Contents...........................................................................................................................ii Revision History.............................................................................................................................ii 1. Introduction..............................................................................................................................1 1.1 Purpose.................................................................................................................................. 1 1.2 Document Conventions........................................................................................................... 1 1.3 Intended Audience and Reading Suggestions............................................................................ 1 1.4 Product Scope........................................................................................................................ 1 1.5 References............................................................................................................................. 1 2. Overall Description..................................................................................................................2 2.1 Product Perspective................................................................................................................ 2 2.2 Product Functions................................................................................................................... 2 2.3 User Classes and Characteristics.............................................................................................. 2 2.4 Operating Environment........................................................................................................... 2 2.5 Design and Implementation Constraints................................................................................... 2 2.6 User Documentation............................................................................................................... 2 2.7 Assumptions and Dependencies............................................................................................... 3 3. External Interface Requirements...........................................................................................3 3.1 User Interfaces....................................................................................................................... 3 3.2 Hardware Interfaces................................................................................................................ 3 3.3 Software Interfaces................................................................................................................. 3 3.4 Communications Interfaces..................................................................................................... 3 4. System Features........................................................................................................................4 4.1 System Feature 1.................................................................................................................... 4 4.2 System Feature 2 (and so on)................................................................................................... 4 5. Other Nonfunctional Requirements.......................................................................................4 5.1 Performance Requirements...................................................................................................... 4 5.2 Safety Requirements............................................................................................................... 5 5.3 Security Requirements............................................................................................................ 5 5.4 Software Quality Attributes..................................................................................................... 5 5.5 Business Rules....................................................................................................................... 5 6. Other Requirements................................................................................................................5 Appendix A: Glossary....................................................................................................................5 Appendix B: Analysis Models.......................................................................................................5 Appendix C: To Be Determined List............................................................................................6 13  Uses of SRS 1. Project managers base their estimation of schedule, effort and resources on it 2. Developers need it to develop products 3. Testing group needs it to develop test plan. 4. The maintenance and support staff need it to understand what system should do 5. Document, manuals, etc. are written based on it. 6. Customers use it to determine what product to expect. 7. Can be used to develop training materials 14  SRS Validation It is extremely important to detect errors in SRS document before going to other phases of system development, Errors may includes: 1. Omission: some user requirements are not included. 2. Inconsistency: contradiction between user requirements. 3. Incorrect facts. 4. Ambiguity: some requirements have multiple meanings. 15  Approaches to Requirement Representation Kassab et al. (2014) found that 60% of respondents reported that requirements were expressed in terms of natural language, that is, informally 16  Requirement format Each requirement should be in a form that is clear, concise, and consistent in use of language. A simplified standard requirement form is:  The [noun phrase] shall (not) [verb phrase] Consider these two requirements for the baggage handling system:  The system shall reject untagged baggage  The system shall not reject damaged baggage It is important to identify requirements in some way for ease of reference, usually with hierarchical numbering. Hence the standard form for a requirement extends to the following:  [identifier] The [noun phrase] shall (not) [verb phrase] 1.2.1 The system shall reject untagged baggage. 1.2.2 The system shall not reject damaged baggage 17  Requirement format Finally, it is desirable to place measurable constraints on performance for functional requirements whenever possible, enriching the standard requirement form to: [identifier] The [noun phrase] shall (not) [verb phrase] [constraint phrase] 1.2.1 The system shall reject untagged baggage within 5 seconds of identification “Shall” is a command word or imperative that is frequently used in requirements specifications. Other command words and phrases that are frequently used include “should,” “must,” “will,” “responsible for”, and there are more 18  Shall or Shall Not? When writing requirements, it is generally preferred to use the positive form, rather than the negative form. That is, the requirement should be written using “shall” statements rather than “shall not” statements. IEEE 29148 advises against writing “shall not” requirements altogether. But it is possible, and sometimes desirable, for there to be exceptions particularly for those requirements pertaining to hazards. 19  Avoiding Imprecision in Requirements All requirements in a specification document should be precise. That is by using measurable quantities and avoiding vague modifiers such as: – countless, some, approximately, huge, tiny, microscopic, and so on. These vague words need to be replaced with measurements 20 Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Anatomy of a Good User Requirement Defines the system under discussion Verb with correct identifier (shall or may) The Online Banking System shall allow the Internet user to access her current account balance in less than 5 seconds. Defines a positive end result Quality criteria Identifies the system under discussion and a desired end result that is wanted within a specified time that is measurable The challenge is to seek out the system under discussion, end result, and success measure in every requirement Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Example of a Bad User Requirement No identifier for the verb The Internet User quickly sees her current account balance on the laptop screen. X Vague quality criteria What versus how It describes how the requirement should be fulfilled ("on the laptop screen"), which is detailing the implementation (the 'how') rather than focusing on the user's need or objective (the 'what'). User requirements should focus on the 'what'—the user's needs or tasks—rather than specifying how the system achieves those needs. Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Standard for Writing a Requirement Look for the following characteristics in each requirement Feasible (not wishful thinking) Needed (provides the specifics of a desired end goal or result) Testable (contains a success criterion/other measurable indication of quality) Clear, unambiguous, precise, one thought Prioritized ID Note: several characteristics are mandatory (answer a need, verifiable, satisfiable) whereas others improve communication Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Writing Pitfalls to Avoid Never describe how the system is going to achieve something (over-specification), always describe what the system is supposed to do Designing the system too early may possibly increase system costs Do no mix different kinds of requirements (e.g., requirements for users, system, and how the system should be designed, tested, or installed) Do not mix different requirements levels (e.g., the system and subsystems) Danger signs: high level requirements mixed in with database design, software terms, or very technical terms Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Writing Pitfalls to Avoid “What versus how” test The system shall use Microsoft Outlook to send an email to the customer with the purchase confirmation. X The system shall inform the customer that the purchase is confirmed. Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Writing Pitfalls to Avoid Do not use vague indefinable terms Many words used informally to indicate quality are too vague to be verified Danger signs: user-friendly, highly versatile, flexible, to the maximum extent, approximately, as much as possible, minimal impact The Easy Entry System shall be easy to use and require a minimum of training except for the professional mode. X Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Writing Pitfalls to Avoid Do not make multiple requirements Keep each requirement as a single sentence Conjunctions (words that join sentences together) are danger signs: and, or, with, also Do not ramble Long sentences with arcane language References to unreachable documents The Easy Entry Navigator module shall consist of order entry and communications, order processing, result X processing, and reporting. The Order Entry module shall be integrated with the Organization Intranet System and results are stored in the group’s electronic customer record. Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Writing Pitfalls to Avoid Do not express suggestions or possibilities Suggestions that are not explicitly stated as requirements are invariably ignored by developers Danger signs: may, might, should, ought, could, perhaps, probably Avoid wishful thinking Wishful thinking means asking for the impossible (e.g., 100% reliable, safe, handle all failures, fully upgradeable, run on all platforms)1``1 The Easy Entry System may be fully adaptable to all situations and often require no reconfiguration by the user. X Martha can’t … Good & Bad Standard Pitfalls to Avoid A Few Simple Tests Summary & Tools Rate these Requirements The Order Entry system provides for quick, user- X friendly and efficient entry and processing of all orders. Invoices, acknowledgments, and shipping notices shall X be automatically faxed during the night, so customers can get them first thing in the morning. Changing report layouts, invoices, labels, and form letters shall be accomplished. X The system has a goal that as much of the IS data as X possible be pulled directly from the T&M estimate.  Data Flow Diagram (DFD) DFD is a graphical representation that provides information flow and transformation between inputs and outputs. DFD purpose is to clarify system requirements and identify major transformation. 31  Data Flow Diagram (DFD) Symbols used in DFD: 32  Data Flow Diagram (DFD) Example of DFD 33  Data Flow Diagram (DFD) Example of DFD 34  Data Dictionary A catalogue of all elements in a system DFD shows the flow of information while data dictionary gives the detail of information 35  Data Dictionary Date dictionary store the following information: 1.Name of data item. 2.Aliases (other names for data). 3.Description/purpose. 4.Related data item. 5.Range of values. 6.Data Structure definition. 36  Data Dictionary Notation + of Data dictionary: A plus sign indicates one element is followed by or concatenated with another element. [ ] Square brackets are used to enclose one or more optional elements. | Or / A vertical line or slash stands for "or" and is used to indicate alternatives. {} Curly braces indicate that the element being defined is made up of a series of repetitions of the element(s) enclosed in the brackets. The upper limit on the number of allowable repetitions {} y can be indicated by including an integer superscript on the right bracket. Here y represents an integer and indicates that the number of repetitions cannot be greater than y. ( ) Optional data 37  Data Dictionary Example of Data dictionary: sequence: Mailing-address= name + address + city + zip-code *The address at which the customer can receive mail* repetition: Completed-order = { item-ordered } * A complete customer order * selection: Atm-transaction = [ deposit | withdrawal ] *An customer transaction at an automated teller machine* 38  Data Dictionary Example of Data dictionary: Name: hidden word Alias: secret word Description: the word the player is trying to guess Definition: hidden word = {alphabetic character}30 name: continue choice alias: none description: whether the user wants to play again or not definition continue choice = [yes | no ] 39  Entity-Relationship (ER) Diagram It is a detailed logical representation of data. Its main components: 1.Data Entities. 2.Entities relationships. 3.Entities Attributes. 40  Entity-Relationship (ER) Diagram ER Diagram notations 41  ER diagrams are primarily used in the context of database design ER diagrams are not limited to databases alone; they can be applied in various other areas as well, including modeling the data requirements of a system ER helps in understanding the relationships between different entities in the system which can help in analysis and design 42  Entity-Relationship (ER) Diagram ER diagram Example 43  Decision Table Used to express complex conditions and associated action. Used to model complicated logic. Decision table consist of 4 four Quadrants: 1. Condition stub: refers to the part of a decision table where the conditions (also known as inputs or criteria) are listed 2. Condition rules 3. Action stub 4. Action rules 44  Decision Table Decision Table Example: Requirement: A customer requests a cash withdrawal. the ATM machine pays out the amount if the customer has sufficient funds in account or if the customer has the credit granted 45  Decision Table How to create decision table: 1- Analyze the requirement and create the first column. 46  Decision Table How to create decision table: 2- Add Columns: Calculate how many columns are needed in the table, fill them with T(True) or F(False). 47  Decision Table How to create decision table: 3- Reduce the table Mark insignificant values with “-“, then remove the duplicate columns 48  Decision Table How to create decision table: 4- Determine actions 49 END OF CHAPTER 50