Requirements Engineering A Good Practice Guide

1. Requirements Engineering A Good Practice Guide EECS812 : Software Requirement Spring 2010 Presenter : Sara Mohseni Instructor : Dr. Hossein Saiedian

2. Organization • Introduction • Requirements Analysis and Negotiations Guidelines • Describing Requirements Guidelines • Requirements Validation Guidelines • Requirements Management Guidelines • System Modeling Guidelines • Requirements Engineering for Critical Systems Guidelines • Summary

3. Requirements Analysis and Negotiations • After an initial set of requirements has been discovered, you should analyze them for conflicts, overlaps, omissions and inconsistencies. • When information from this analysis is available, system stakeholders then negotiate to agree on a set of system requirements. • Conflicts must be resolved and requirements prioritized.

4. Requirements Analysis and Negotiations Guidelines • Define system boundaries • Use checklists for requirements analysis • Provide software to support negotiations • Plan for conflicts and conflict resolution • Prioritize requirements • Classify requirements using a multi-dimensional approach • Use interaction matrices to find conflicts and overlaps • Assess requirements risks

5. Classify Requirements using a Multi-Dimensional Approach • You should classify your requirements so that you can identify related requirements. • You should not necessarily put individual requirements into a single class but should derive several ways of classifying your requirements for analysis. • Several ways of classification is called multi-dimensional classification. Each requirement may therefore fall into a number of different classes.

6. Classify Requirements using a Multi-Dimensional Approach • Benefits: • Classifying requirements is a basis for discovering commonalities and unexpected relationships between them. Conflicts and overlaps are most likely between requirements in the same class. Sometimes you find that requirements are so similar that they can be combined. • Classifying requirements improves the traceability of requirements document. When changes are made to requirements in some class, it may be helpful to consider if other requirements in the same class are affected by the change.

7. Classify Requirements using a Multi-Dimensional Approach • Benefits: • Classification can help you find missing requirements. If you find that there are no requirements in some class which is part of your normal classification scheme, this may mean that important requirements have been left

8. Classify Requirements using a Multi-Dimensional Approach • Implementation: • The simplest way to classify requirements is to use what is called a faceted approach. You identify a number of dimensions or facets and identify keywords which describe each of these. • After deciding on an initial set of classification terms, you should then go through the requirements, associating one or more of these keywords with each of them.

9. Classify Requirements using a Multi-Dimensional Approach • Implementation: • Once requirements have been classified, you extract groups of requirements with the same classification terms for comparison and analysis. To do this, you need to use some software which will allow you to tag each requirement with its classification terms and then construct a request to the system to find all requirements with a given tag. • This is possible if you use a word processor system to manage your requirements, but it is simpler if requirements are managed in a database.

10. Classify Requirements using a Multi-Dimensional Approach • Possible keywords to classify requirements: • System: This should be applied to requirements which affect the entire system such as performance or reliability requirements. • User interface: This should be applied to requirements which are concerned with user interaction. More detailed classifications may also be used such as ‘user input’, ‘data presentation’, ‘error indication’, etc. • Database: This should be applied to requirements which are concerned with the data managed by the system.

11. Classify Requirements using a Multi-Dimensional Approach • Possible keywords to classify requirements: • Communications: This should be requirements which are concerned with the external communication facilities in the system. Again, it may be broken down into more detailed classifications reflecting, perhaps, the data communications equipment. • Security: This should be applied to requirements which are likely to have security implications.

12. Classify Requirements using a Multi-Dimensional Approach • Costs and problems: • Introducing this guideline is not expensive. You will need a short training session that illustrates how requirements can be classified and how this allows groups of related requirements to be compared. • The costs of applying this guideline are the costs of defining a classification scheme for a particular set of requirements and assigning classifications to each requirement.

13. Classify Requirements using a Multi-Dimensional Approach • Costs and problems: • A problem, of course, is that requirements do not always fit neatly into classes and it is difficult to decide which classifications to assign. • If you have very large numbers of requirements, you can apply this guideline hierarchically. That is, you can identify an initial set of classes and apply these to the requirements to create principal grouping. For each principal group of requirements you can then devise more detailed classifications and apply these to that group.

14. Describing Requirements • Descriptions of individual requirements should be concise, understandable and unambiguous. • In most organizations, system requirements are written as paragraphs of natural language, supplemented by diagrams. • Natural language can be used to describe requirements clearly. All too often, however, natural language requirements are difficult to understand. • Natural language can be ambiguous, surprisingly opaque and is often misunderstood.

15. Describing Requirements • Common problems with natural language: • The requirements are written using complex conditional clauses (if A then if B then if C…) which are confusing. • Terminology is used in a sloppy and inconsistent way. • The writers of the requirement assume that the reader has specific knowledge of the domain or the system and they leave essential information out of the requirements document.

16. Describing Requirements • There are three essential things that you must bear in mind when considering how to improve your requirements descriptions: • Requirements are read more often than they are written. Investing effort in writing requirements which are easy to read and understand is almost always cost effective. • Readers of requirements come from diverse backgrounds. If you are a requirements writer, you should not assume that readers have the same background and knowledge as you.

17. Describing Requirements • There are three essential things that you must bear in mind when considering how to improve your requirements descriptions: • Writing clearly and concisely is not easy. If you do not allow sufficient time for requirements descriptions to be drafted, reviewed and improved, you will inevitably end up with poorly written specifications. • You must decide on the level of detail for describing requirements based on the type of requirements, customer expectations, organizational procedures, and external standards or regulations.

18. Describing Requirements Guidelines • Define standard templates for describing requirements • Use language simply, consistently and concisely • Use diagrams appropriately • Supplement natural language with other descriptions of requirements • Specify requirements quantitatively

19. Use Language Simply, Consistently and Concisely • When you express a requirement in natural language, write your descriptions using simple and concise language. Wherever possible you should avoid complex sentence constructions, long sentences and paragraphs and ambiguous terminology.

20. Use Language Simply, Consistently and Concisely • Benefits: • When requirements are written using simple language, they are easier to read and understand. The principal costs of requirements engineering are the costs of paying people to read requirements. If you can reduce the time required for requirements reading without losing understanding, you will have an immediate cost saving in your requirement process. • It takes less time to explain the requirements to stakeholders and a wider range of people can participate in the validation of the requirements.

21. Use Language Simply, Consistently and Concisely • Implementation: • Many people find it difficult to write clear and concise natural language. • To improve requirements descriptions, we recommend that you should write a short style guide which describes how to use language in writing requirements in your organization. • The guide must be short and easy to read. • Your style guide should include four or five pages of guidelines with examples of good and bad writing drawn from your own experience.

22. Use Language Simply, Consistently and Concisely • Basic writing style guidelines: • Keep sentences short. • Never express more than one requirement in a single sentence. • Avoid the use of jargons, abbreviations and acronyms. The same acronym may have different meanings in different domains. • Keep paragraph short. As a general rule, no paragraph should be made up of more than seven sentences. • Use lists and tables wherever possible to present information sequence.

23. Use Language Simply, Consistently and Concisely • Basic writing style guidelines: • Use terminology consistently. Do not use a term to mean one thing in one place in the document and something different somewhere else. Using a data dictionary to define the names of system entities can be helpful here. • Do not express requirements using nested conditional clauses (i.e. if X then if Y then R1a else if Z then R1b else R1c). These are very easy to misunderstand. If you can not find a convenient way of expressing a requirement in natural language without nested conditional clauses, use a different notation such as a decision table.

24. Use Language Simply, Consistently and Concisely • Basic writing style guidelines: • Use the active rather than the passive voice, particularly when describing actions taken by people or the system. • Do not try to express complex relationships in a natural language description. Diagrams are much more effective for this purpose. • Never use anonymous references. When you refer to other requirements, tables or diagrams, give a brief description of what you are referring to, as well as the reference number.

25. Use Language Simply, Consistently and Concisely • Basic writing style guidelines: • Pay attention to spelling and grammar. Poor spelling and grammar can obscure your meaning. • Use words such as ‘shall’, ‘should’, ‘will’ and ‘must’ in a consistent way with the following meanings: • ‘shall’ indicates that the requirement is mandatory. • ‘should’ indicates that the requirement is desirable but not mandatory. • ‘will’ indicates something that will be externally provided. • ‘must’ is best avoided. If used, it should be synonym for ‘shall’.

26. Use Language Simply, Consistently and Concisely • Costs and problems: • The principal costs of introducing this guideline are the writing of a style guide and, if necessary, short training sessions for all involved in the RE process. • Initially, you will probably find that it is quite expensive to introduce this guideline in to your requirements engineering process. Perhaps, it takes longer to write requirements simply than in a more complex way. However, as people gain experience with clear writing style, these costs will rapidly decline.

27. Use Language Simply, Consistently and Concisely • Costs and problems: • The problem that you are likely to face is that many people from a technical background find it very difficult to write clearly and concisely. Introducing a style guide is all very well but we have a long tradition of writing requirements in an opaque and obscure way and this can not be changed overnight.

28. Supplement Natural Language with Other Descriptions of Requirements • Some requirements are best described using specialized notations, such as mathematical formulae, decision tables, design notations or programming languages, rather than natural language. • Although you will almost always want to have some description in natural language, you should supplement this, where appropriate,, with more precise descriptions in an appropriate notations.

29. Supplement Natural Language with Other Descriptions of Requirements • Benefits: • Specialized notations allow for descriptions whose meaning is less likely to be misinterpreted than a natural language description. The description is often more concise than a corresponding natural language description. • If the notation used is familiar to application domain experts, they are less likely to make mistakes when specifying their requirements and more likely to find any errors which have been made.

30. Supplement Natural Language with Other Descriptions of Requirements • Implementation: • Supplement decision tables where actions have to be taken depending on a complex set of conditions. • Supplement programming languages or program design languages which may be used where you wish to describe a number of actions which must take place in sequence and where some of these actions are conditional or may be repeated. You may also use language descriptions for detailed interface description. • Supplement algebra when you wish to describe how particular numeric values must be transformed

31. Supplement Natural Language with Other Descriptions of Requirements • Implementation: • Supplement algebra when you wish to describe how particular numeric values must be transformed by an operation or particular values should be computed. • Supplement data-flow diagrams where you need to define a sequence of transformations which take place during some end-to-end processing of data. • Supplement timing diagrams to illustrate time-critical system actions.

32. Supplement Natural Language with Other Descriptions of Requirements • Implementation: • Supplement system models such as object models, entity-relation models or finite state models where you need to describe detailed system requirements.

33. Supplement Natural Language with Other Descriptions of Requirements • Costs and problems: • In most cases, introducing this guideline does not require engineers to learn new notations but to use techniques which they already know. In such cases, there are no introductory costs for this guideline. • We advise against introducing new unfamiliar notations as these are likely to cause more problems than they solve. • There are obviously some costs in applying the guidelines as tables, models, etc., have to be created.

34. Supplement Natural Language with Other Descriptions of Requirements • Costs and problems: • A possible problem may arise if mathematical or unfamiliar notations such as decision tables are used. Some readers of the requirements may think that a requirement is harder to understand because they do not know the notation. They may therefore oppose the use of these notations. • To overcome this resistance, you may find it helpful to demonstrate that the more concise notations can be paraphrased in natural language.

35. Requirements Validation • After the requirements document has been produced, the requirements should be formally validated. This validation process is concerned with checking the: • Omissions • Conflicts • Ambiguities • Requirements follow quality standards

36. Requirements Validation Guidelines • Check that requirements document meets your standards. • Organize formal requirements inspections. • Use multi-disciplinary teams to review requirement. • Define validation checklists. • Use prototyping to animate requirements. • Write a draft user manual. • Propose requirements test cases. • Paraphrase system models.

37. Write a Draft User Manual • Using the requirements document as a system specification, write an initial draft of the user manual of the system. This should cover all aspects of the system functionality and, where necessary, you should make plausible assumptions about the system user interface.

38. Write a Draft User Manual • Benefits: • Writing a user manual during the validation process forces the detailed analysis of requirements and helps reveal problems concerning the actual use of the system. It means that system usability issues are uncovered before system development begins. • Writing the user manual at this stage may be necessary or useful for users who are experimenting with a system prototype. The document may help clarify user interface design issues, as it can illustrate good interface design and design features which should be avoided.

39. Write a Draft User Manual • Implementation: • A draft user manual explain the system facilities described in the requirements in terms that end-users can understand. • You should write the manual by systematically translating the functionality described in the requirements into descriptions, written in end-user terms, of how to use them. Someone with an overall understanding of the system and experience of writing user manuals should be responsible for this.

40. Write a Draft User Manual • Implementation: • If they find it difficult to explain a function to end-users or to explain how to express system functionality, this suggests that there is a requirements problem. These problems should be raised and documented using a standard requirements review form.

41. Write a Draft User Manual • Costs and problems: • There are no significant costs involved if you have people available who have previous experience of writing user documentation. The costs of applying the guideline are the costs of actually writing the manual. • The principal difficulty with this guideline is finding the time and the people to write the manual. Writing takes a long time and if your schedule is very tight, it may be impossible to implement this guideline. This problem is particularly acute in small companies which rarely have specialist documentation writers.

42. Propose Requirements Test Cases • For each requirement, propose one or more possible tests which can be used to check if the system meets that requirement.

43. Propose Requirements Test Cases • Benefit: • Proposing possible tests is an effective way of revealing requirements problems such as incompleteness and ambiguity. If there are difficulties in deriving test cases for a requirement , this implies that there is some kind of requirement problem. There may be missing information in the requirement or the requirement description may not make clear exactly what is required. • The proposed set of test cases can be used as a basis for test planning and the derivation of actual test cases to be applied to the final system.

44. Propose Requirements Test Cases • Implementation: • For each requirement in the requirements document, you should analyze that requirement and define a test which can objectively check if the system satisfies the requirement. The objective of proposing test cases for requirements is to validate the requirement rather than the system. • You need not be concerned with practicalities such as testing costs, avoiding redundant tests, detailed test data definition, etc.

45. Propose Requirements Test Cases • Questions to ask to define test cases: • What usage scenario might be used to check the requirement? This should define the context in which the test should be applied. • Does the requirement, on its own, include enough information to allow a test to be defined? If not, what are requirements should be examined to find this information? If you need to look at other requirements, you should record these as there may be dependencies between requirements which are important for traceability.

46. Propose Requirements Test Cases • Questions to ask to define test cases: • Is it possible to check the requirement using a single test or are multiple test cases required? If you need several tests, this may mean that there is more than one requirement embedded in a single requirement description. • Could the requirement be re-stated so that the required test cases are fairly obvious?

47. Propose Requirements Test Cases • Test Recording Form: You should design a test recording form which you fill in for each requirement checked. This should include at least the following information: • The requirement identifier • Related requirements • A brief description of the test which could be applied and why this is an objective requirements test • A description of requirements problems which made test definition difficult or impossible • Recommendations for addressing requirements problems • Could the requirement be re-stated so that the required test cases are fairly obvious?

48. Propose Requirements Test Cases • Costs and problems: • The initial costs of introducing this guideline are fairly low as it does not require any investment in new methods or technology. You will, however need a training session to demonstrate the value of writing test cases at this stage. • There are moderate costs involved in applying this guideline. Test cases may take anything from a few minutes to a few hours to design. This systematic approach to validation will take longer than simply reading the requirements and noting possible problems. However, this is compensated for by reduced test planning costs where many test cases may be reduced.

49. Propose Requirements Test Cases • Costs and problems: • The initial costs of introducing this guideline are fairly low as it does not require any investment in new methods or technology. You will, however need a training session to demonstrate the value of writing test cases at this stage. • There are moderate costs involved in applying this guideline. Test cases may take anything from a few minutes to a few hours to design. This systematic approach to validation will take longer than simply reading the requirements and noting possible problems. However, this is compensated for by reduced test planning costs where many test cases may be reduced.

50. Propose Requirements Test Cases • Costs and Problems: • You may encounter some resistance to this guideline because requirements engineers see the derivation of test cases to be someone else’s responsibility. You need to make clear that they are not defining the actual tests which will be applied to the system. You need to make clear that they are not defining the actual tests which will be applied to the system. You should emphasis that any errors made in the tests themselves are not important so as long as they help the requirements validation process.