Natural Language Specification

Transcription

1 REQUIREMENTS ENGINEERING LECTURE 2017/2018 Dr. Jörg Dörr Natural Language Specification

2 Most Requirements are Described in Natural Language Free Text (Prose) In Word In Excel (Tabular) In RM-Tools In Sys-ML Scenarios Stories as ordered text segments Tabular / Templates Use Cases Mostly according to structured template 2

3 Examples 3

4 Examples 4

5 Examples 5

6 Examples (1) The driver turns on the route guidance system. (2) The guidance system determines current position (3) The navigation system requests the destination. (4) The driver enters the desired destination. (5) The guidance system offers route options. (6) The driver selects the prefered route options. (7) The navigation system calculates the ideal route. (8) The navigation system displays the first waypoint on the screen. 6

7 Examples 7

8 Examples HSA2 Use Case Name Goal Actor Preconditions Description Exceptions Business Rules Quality requirements Data (Data model) System Functions Postcondition Create request Record all incoming requests in the system. First-line supporter The Actor is logged in as First-Line Supporter (See Use Case HSA6. Login) 1. The Actor 1.1 receives request via phone or in person or via 1.2 triggers a new request 2. The system requests the actor to specify data associated to the request. 3. The Actor 3.1 specifies data associated to the request 3.2 triggers the system to save the request 2. The system 2.1 saves the new request 2.2 records the request 2.3 displays the new request in the list of hotline requests 2.4 marks request as first line - Only problems with high priority are allowed to be requested via phone or in person. For statistical purpose it is not allowed to create a request for more than one problem. The Actor must use the existing employee database to select the user during step 3.1. (Not in scope of experiment) Employee data (issued by) Problem (Description, Category, Cause) Request (Request Number, Priority, created by, Creation Time) SA2. Provide template SA3. Save request SA4. Record request and processing information SA5. Update list of hotline requests SA9: Set state The problem request is created in the system and can be further processed. 8

9 How to Write Good (Natural Language) Requirements? 9

10 Typical Quality Problems of Requirements (1) Syntactics Badly structured Risk: barely extendable, hardly readable Incomprehensible Risk: incorrect transformation, not traceable, not testable Ambiguous and vague Risk: incorrect transformation, not testable Redundant Risk: hardly changeable, barely refineable, slightly inconsistent 10

11 Typical Quality Problems of Requirements (2) Semantics Inconsistent Risk: incorrect transformation, hardly correctable Incomplete Risk: solutions that do not fulfill important expectations or solutions, behave incorrectly under certain circumstances Incorrect Risk: solutions that do not behave as they are intended to (wrong behavior) 11

12 Typical Quality Problems of Requirements (3) Authority Superfluous (nobody asks for the requirement) Risk: unnecessary developments costs or solutions that do not behave as they are intended to Too constricting Risk: not feasible Inconsistent with standards, laws, previous documents Risk: no approval 12

13 Characteristics of Good Requirements (Documents) according to IEEE 830 correct unambiguous (only one possible interpretation) complete (all functional and non-functional requirements, all system reactions and unintended inputs are specified) consistent (no inconsistencies, consistent use of terminology) ranked for importance verifiable (measurable and testable ) modifiable (clear structure, overview, no redundancy) traceable (to design/test but also internally in user/developer documents) (understandable) 13

14 Correctness A requirement is correct if all relevant stakeholders confirm it and if the requirement has to be completely implemented in the future system. If the requirement unnecessarily increases the systems range of functions, it is not correct. Can be (constructively) ensured by: Systematic derivation from superior requirements/ goals Avoidance of gold-plating 14

15 Completeness (1) A requirement is complete if it is documented according to defined criteria and if there are no content-related vacancies Incomplete requirements leave a margin for additions 15

16 Completeness (2) Example of an incomplete requirement: As soon as the login window appears, customer-specific information has to be entered. Who enters the information? Which information? Complete: appears, the user has to enter his customer number, address and password. Can be (constructively) ensured by: Use of active instead of passive formulation Writing verifiable requirements 16

17 Completeness (3) A Software Requirements Specification is complete if every single requirement is specified completely and if the specification contains all relevant requirements. Can be (constructively) ensured by: Attention to standard contents Systematic derivation from superior requirements/ goals 17

18 Unambiguousness (1) A requirement is unambiguous if it is verbalized in such a way that only one valid interpretation is possible. Ambiguous requirements often lead to undesired implementations of the requirement in the system. 18

19 Unambiguousness (2) Example: For authentication, the driver enters an electronic card and a PIN. If it is invalid, the vehicle cannot be started. ambiguous requirement! Ambiguous: What is invalid? The card or the PIN, or both of them? Unambiguous: and a PIN. If the PIN is invalid, the vehicle cannot be started. 19

20 Unambiguousness (3) Can be (constructively) ensured by: Avoiding passive formulations Wrong: The result is shown Right: The system shows the result Avoiding relative clauses/ nested sentences Avoiding weak words 20

21 Example List of Weak Words a little, about, accordingly, actual, adequate, again, all but, almost, also, analogous, another, anything, apparent, approximately, articulate, as a whole, at the most, basic, besides, best, better, big, bit, certain, certainly, circa, clear, clearly, close by, closely, common, conditionally, considerable, decided, dedicated, defined, definite, detailed, determinately, different, directly, distinct, diverse, else, enough, especially, evidently, explicit, extensive, extremely, few, grand, great, however, huge, if need, improved, in detail, in most instances, indeed, just, largely, later, like, likewise, limited, long-standing, maybe, mostly, much, nearly, necessarily, no case, no way, not exhaustive, obvious, of course, ongoing, or so, ordinary, other, particular, perhaps, persistent, possible, powerful, precise, presently, prodigious, provisory, qualified, quite, related, satisfactory, seemingly, self-evident, separately, several, shortly, similar, some day, something, sometimes, soon, special, still, sufficient, sure, sustained, to be announced, to be confirmed, to be defined, to be desired, to be detailed, to be determined, too, ultimate, 21 uncommon, unique, unlike, usual, well, where

22 Traceability A requirement is traceable if the origin of the requirement is clear and if it facilitates the referencing of each requirement in future development or enhancement documentation. (means traceability from its origin passing different refinement and specification steps to its realization in requirement- and development artifacts) Traceability of requirements supports, e.g., verifiability, acceptance, change management, quality management, etc. Can be (constructively) ensured by using: Unique identification numbers Matrices, graphs Explicit references 22

23 Understandability A requirement is understandable if the subject of the requirement is easy to comprehend Can be (constructively) ensured by: Using simple sentences Using short paragraphs Describing one single requirement per sentence Providing a glossary Using bullet lists instead of long sentences Avoiding nested sentences Cautiously using abbreviations Avoiding passive sentences 23

24 Example Negative Users attempting to access the ABC database should be reminded by a system message that will be acknowledged and on page headings on all reports that the data is sensitive, and access is limited by their system privileges. Positive? 4.1 The system shall notify users attempting to access the ABC database that the ABC data is classified as sensitive access to the ABC data is limited to the extent allowed by the user s system privileges page heading on all reports generated using the ABC database must state that the report contains sensitive information The system shall require the user to acknowledge the notification before being allowed to access the ABC database. 24

25 Consistency (1) A requirement is consistent if statements of a requirement do not contain any contradiction and are not in conflict with each other. In the case of a software requirements specification, not only do individual requirements have to be consistent, but it is also important that no subset of individual requirements described in it conflicts. 25

26 Consistency (2) A software requirements specification is internally consistent if, and only if, no subset of individual requirements described in it conflicts. The tree types of likely conflicts in a software requirements system are as follows: (1)Inconsistent description of real-world context (2)Inconsistent attributes of a real-world context (3)Logical or temporal conflict between two specified requirements 26

27 Consistency (3) Examples of inconsistency: Ad (1): Different terminology of similar objects (e.g. Input of travel destination, Input of destination place, Input of destination ) Ad (2): In at least 2 requirements, attributes of objects may conflict (e.g., one requirement may state that input is via keyboard while another may require voice input) Ad (3): There may be logical or temporal conflicts between two requirements (e.g., one requirement may state that A must always follow B, while another may require that A and B occur simultaneously. 27

28 Consistency (4) Can be (constructively) ensured by: Using a glossary Avoiding synonyms (use of different terms for the same object e.g., customer number customer ID ) Avoiding homonyms (words that share the same spelling and pronunciation but have different meanings, e.g., bank ) 28

29 Verifiability (1) A requirement is verifiable if a person or machine can check that the software product meets the requirement. In general, any underspecified requirement is not verifiable. 29

30 Verifiability (2) Examples The usual response time of the system shall not be more than 20 seconds. Not verifiable requirement Verifiable requirement: Output of the program shall be produced within 20s of event E1 60% of the time; and shall be produced within 30s of event E1 100% of the time. Can be (constructively) ensured by: Providing a specific, quantified description Writing testable requirements 30

31 Ranked for Importance and/or Stability A requirement is ranked for importance and/or stability if it has an identifier to indicate either the importance or stability of that particular requirement. Can be (constructively) ensured by: Prioritizing Essential, helpful, nice to have Other definitions, attributes, section headings 31

32 Modifiability and Readability Are defined by the structure and layout of the document A software requirements specification is modifiable if, and only if, its structure and style are such that any changes to the requirements can be made easily, completely, and consistently while retaining the structure and style. (IEEE ) A software requirements specification is readable if, and only if, the reader can comprehend its content easily Can be (constructively) ensured by: Coherent (logical) structure Obvious identification of requirements, atomic description of requirements Avoiding unnecessary redundancy Linking 32

33 Writing Guidelines for Requirements Goal: Natural Language Requirements are easier to read and therefore easier to understand Writing guidelines consider common problems, project-specific additions may be useful Guidelines should be summarized into company-specific writing guidelines 33

34 Writing Guidelines for Single Requirements (1) Short sentences Subject Predicate - Object Describe just one single requirement per sentence Avoid and Avoid colloquial language Economical use of abbreviations Short paragraphs 7 sentences maximum Bullet lists instead of long sentences Consistent use of notations and terminology Avoid nested sentences about logical connections Allocate requirements to unique identifier Avoid gold-plating (embellishments, additional functions) 34

35 Writing Guidelines for Single Requirements (2) Illustrate the emphasis of requirements Use words like have to should or can only if their meaning has been defined before (e.g., have to or should means that the requirement is obligatory) Separate optional from obligatory requirements by using a definition, a suitable attribute, or a heading Justify requirements Use active instead of passive sentences Wrong: The result is shown Right: The system shows the result (clearly defines who is the actor) Illustrate complex circumstances/ dependencies with the help of graphics Use correct and precise references Use automated spell check 35

36 Writing Guidelines for Single Requirements (3) Write testable requirements for verifying whether the system can fulfill the requirements Is it possible to create a test case from requirement X? Avoid generalization Leads to ambiguity Document the origin of each requirement Having a huge set of requirements, it will be difficult to remember the origin of every requirement if a requirement has to be changed (e.g., in case of a conflict) Explanations in requirements are confusing Bad example: To work as efficiently as possible, the experienced user s access rights are verified by a double click on a list entry and if his confirmation is valid, customer-specific information is shown in the field Access. If an exception is thrown from the SQL request, then Better solution: Explicit labeling of explanations and rationale 36

37 Sentence Pattern in English 37

38 Short Exercise: take 5 minutes and produce example sentences that follow that pattern (e.g. for a smart phone) 38

39 Satzschablone of Chris Rupp (Controlled NL) 39

40 Writing Guidelines for Software Requirements Specifications Define an obvious document structure Add a glossary Avoid synonyms/ homonyms Ensure traceability of requirements 40

41 Natural Language Summary Natural Language is still the most common technique for specifiying requirements Natural Language can cause many requirements problems Low verifiability, ambiguity, low understandability, etc. Writing guidelines can help avoiding typical problems 41