Requirements Documentation

1. Requirements Documentation Reza Sherafat CAS 703 – Software Design Seminar February 2005

2. Content • Introduction • Requirements Engineering Process • Requirements Documentation Templates • Viewpoint-oriented Requirement Documentation methods • Object-oriented approach • Common Problems

3. Problems in developing computer based systems since 1960s • Too many systems are late or over budget • Systems don't do what the users really want or never used to the effectiveness (there are rarely a single reason for these problems but a major contributory factor is difficulties with system requirements)

4. What are requirements? • A specification of what should be implemented • Defined at early stages of a system development • Include: • how the system should behave • application domain information • constraints on the system's operation • specification of a system property or attribute.

5. What is requirements engineering? • A relatively new term invented to cover all of the activities involved in discovering, documenting and maintaining a set of requirements for a computer-based system. • Use of the term 'engineering' implies that systematic and repeatable techniques should be used to ensure that system requirements are complete, consistent and relevant.

6. How much does requirements engineering cost? • Depends on the type and size of the system being developed • In a survey for large hardware/software systems, about 15% of the total budget is taken up by the requirements engineering activities. For smaller projects it is about 10%.

7. Common requirements' problems • Don't reflect the real needs of the customers • Inconsistent and incomplete • Expensive to make changes to the requirements after they have been agreed • Misunderstandings between customers, those developing the system requirements and software engineers

8. What happens when requirements are wrong? • System may be delivered late or with more cost than originally expected • Customer and end-user might not be satisfied with the system • System may be unreliable in use, with regular system crashes happening all the time. • If system continues in use, the costs of maintaining and evolving are usually very high.

9. What is a requirements engineering process? • Requirements engineering process is a structured set of activities which are followed to derive, validate and maintain a systems requirements document. The activities include: • Requirements elicitation • Requirements analysis and negotiation • Requirements documentation • Requirements validation

10. Requirements elicitation techniques • The system requirements are discovered through consultation with stakeholders, from system documents, domain knowledge • Other names are 'requirement acquisition' or 'requirement discovery'

11. Interviews • Closed loop: interviewer looks for answers to a set of pre-defined questions • Open loop: there are no pre-defined agenda and discussion is done in an open-ended way.

12. Scenarios • Stories of how the system will be used • End-users and other stakeholders find it easier to relate to real-life examples rather than abstract descriptions of functions of a system • They should at least include: • Description of the state of the system before entering the scenario • Normal flow of events in the scenario • Exceptions to the normal flow of events • Information about other activities which might be going at the same time • Description of the state of the system after the scenario

13. An example scenario • Scenario of ordering a report from a library: • The user logs on the system • The order document is issued • The reference number of the document is entered • A delivery option is selected • The user logs out. • Exception: if the reference number is incorrect, the user is offered to enter the document reference or invoke the system help.

14. Requirements Reuse • A good practice to reuse as much knowledge as possible when developing a new system • Although requirements for each system is distinct, there are a number of situations where reuse is possible: • Where requirement is concerned with providing information about the application domain, e.g. constraints on the system. • Where the requirement is concerned with the style of presentation of the information, like the user interface of the whole systems for an organization. • Where the requirements reflect company policies such as security requirements.

15. Prototyping • An initial version of the system which is available early in the development process • Helps elicit and validate the system requirements • 'throw-away' prototypes used to help elicit and analyze the requirements are often called • In contrast evolutionary prototypes are intended to deliver a workable system quickly to the customer

16. Prototyping – cont’d • Prototypes help to establish the overall feasibility and usefulness of the system • The only effective way of developing system user interface. • May be possible to be used in system tests later in the validation process

17. Requirements analysis and negotiation • Aim at discovering problems with the system requirements and reach agreement on changes to satisfy all system stakeholders • Requirements are analyzed in detail • Different stakeholders negotiate to decide on which requirements are to be accepted • Since there are inevitably conflicts between the requirements from different sources, information may be incomplete or may be incompatible with the budget available

18. Analysis checklists • A list of questions which the analyst may use to assess the requirement. Some items in these lists may be: • Premature design • Combined requirements • Unnecessary requirements • Use of non-standard software/hardware • Requirements ambiguity • Conformance with business rules • Requirements testability • Requirements realism

19. Interaction matrices • Used to discover the interactions between requirements and to highlight requirements conflicts and overlaps • If we can not assume that conflicts do not exist, we should assume that there is a potential conflict • Undetected conflicts are much more expensive to resolve

20. Example – Interaction matrices O: OVERLAP C: CONFLICT

21. Requirements negotiation • Discussing conflicts and finding some compromise which all of the stakeholders can live with • Meetings are most effective way. Meetings should be conducted in three stages: • An information stage, explaining the nature of the problem • A discussion stage, in which stakeholders discuss possible solutions • A resolution stage, where actions concerning the requirements are agreed

22. Requirements Documentation • There are many different ways to structure the requirements documents, depending on: • The type of the system being developed • The level of detail included • Organizational practice • Budget • Schedule

23. Standard Templates • Ensures that all the essential information is included • A number of different large organizations such as the US Department of Defense and IEEE have defined standards for requirements documents • Probably the most acceptable of these standards is the IEEE/ANSI 830-1993 • The standard recognizes differences between systems, and allows for some variations in the structure. • There is a list of stable and variant parts: • Stable parts • Variant parts

24. IEEE/ANSI 830 - 1993 • Introduction: • Purpose of the requirements document • Scope of product • Definitions, acronyms and abbreviations • References • Overview of the remainder of the document • General Description: • Product perspective • Product functions • User characteristics • General constraints • Assumptions and dependencies

25. IEEE/ANSI 830 – 1993 – cont’d • Specific requirements • Covering functional, non-functional and interface requirements. These should include external interfaces, functionality, performance requirements, logical requirements, design constraints, system attributes and quality characteristics • Appendices • Index

26. A template based on IEEE/ANSI 830 – 1993 • Preface • Introduction • Definition of the product, its expected usage and an overview of its functionality • Glossary • Definition of technical terms and abbreviations used • General user requirements • The systems requirements from the perspective of the user • System architecture • A high-level overview of the anticipated system architecture, showing the distribution of functions across system modules

27. Example – cont’d • Hardware specification • Optional part for specifying of the hardware that the software system is to expected control • Detailed software specification • Detailed description of the expected system functionality • Reliability and performance requirements • Describes the reliability and performance expected. • Appendices for • Hardware interface specification • Software components • Data structures specification • Data-flow models of the software system • Detailed object models of the software system • Index

28. Requirements validation • The process outputs are as follows: • A list of problems • Agreed solution • Techniques for requirements validation: • Requirements reviews: Involves a group of people who read and analyze the requirements • Pre-review checking: one person carries out a quick standards check to ensure that the documents structure is consistent with defined standards • Review team membership: Stakeholders from different disciplines should be involved

29. User manual development • User manual development: • Rewriting the requirements in a different way is a very effective validation technique. • To rewrite the document you must understand the requirements and the relationships. • Developing this understanding reveals conflicts omissions and inconsistencies. • A user manual should include the following information: • A description of the functionality and how to access the functionality through the user interface • A description of how to recover from difficulties • Installation instructions for users

30. Actors in requirements engineering process • Domain expert: provide information about the application domain and the specific problem in that domain which is to be solved • System end-user: will use the system after delivery • Requirements engineer: eliciting and specifying the requirements • Software engineer: responsible for developing the software system • Project manager: planning and estimating the prototyping project

31. Structured Analysis and Design Technique (SADT) • Developed in the late 1970s by Ross • Based on data-flow models that view the system as a set of interacting activities • Decomposes the problem into a set of hierarchical diagram, each composed of a set of boxes and arrows • Each lower level is documented separately and represents the refinement to the previous level • The most abstract level is the 'context diagram', representing the system's activities with a set of input/outputs.

32. SADT viewpoints • SADT does not have an explicit notion of viewpoints, viewpoints are an intuitive extension Control Input Output ACTIVITY Mechanism

33. Example Item Database User database User database Item availability Library card [Library User] Issue library item Issued item Return Date [Library User] [Issue clerk] Requested Item [Library User] Activity diagram for library system.

34. Example – cont’d Update details User database Item database User detail Item availability User status Library Card Check user Item status Requested item Check item Checked item Issue item Return date Issued item Refinement of the issue library item function

35. Viewpoint-oriented System Engineering (VOSE) • Developed in Imperial College London in early 1960s • VOSE is a framework that addresses the entire system development cycle • Uses data-flow and state transition scheme to model the system world • Requires further examination of consistency between different viewpoints

36. Issue Check Release Example – a VOSE data flow checked item issued item Library user Library user presented item reserve item remove item removed items reserved items reserved item released item Data flow process from the domain of the issue desk

37. Example – a VOSE state transition Off-desk remove check loan Presented Checked On-loan reserve release Reserved State transition diagram seen by the issue desk present use return On-shelf Presented On-loan Finished State transition diagram seen by the library user

38. Use cases • Used in OO Analysis • Definition • Describes the sequence of events of some types of users (actors) using some part of system functionality to complete a process • Actors: A person, organization or external system playing a role in some interactions with the system • Associations: interactions between actors and use cases

39. Use cases – example

40. Use cases – example – cont’d

41. Use Cases Diagrams in UML • Use cases – horizontal ellipses • Actors – stick figures • Associations – lines (the arrowhead indicates the direction of initial invocation) • System boundary box (optional)

42. A simple use case diagram

43. Common problems in writing requirements • Requirements are written in complex conditional clauses 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 of the system and may leave out some essential information

44. Things that the writer should bear in mind • Requirements are read more often than they are written. Invest more effort to write documents that are easy to read and understand • Readers of requirements come from diverse backgrounds. Don't assume that readers have the same background and knowledge as you • Writing clearly and concisely is not easy. Allow sufficient time for drafting and reviewing

45. Guidelines • Define standard templates for describing requirements • Use language simply, concisely and consistently. Use short sentences and paragraphs • Use diagrams appropriately to present overviews and relationships between entities • Specify requirements quantitatively (number of users, response time requirements, etc.)

46. Questions • Q1 – Identify 10 functional system requirements for an online university library system. • Q2 – Write use cases for the library system in Q1 and draw the use case diagrams. • Q3 – Draw state transition and data-flow diagrams for the library system.

47. References • Bahati Sanga, Assessing and improving the quality of software requirements specification documents, McMaster University, 2003 • G. Kotonya, Requirements Engineering, processes and techniques, Wiley, 1997 • R.S. Pressman, Software Engineering, a practitioner's approach, Fifth edition, McGraw-Hill • D.M. Berry, Users manuals as a requirements specification, 2003 • Zhiming Liu, Object-Oriented Software Development with UML, The United Nations University, July 2002 • How to Draw UML 2 Use Case Diagrams, by Scott W. Ambler, available online at http://www.agilemodeling.com/artifacts/useCaseDiagram.htm