THE BaRE METHOD Version 1.0. Uolevi Nikula

Transcription

1 3 THE BaRE METHOD Version 1.0 Uolevi Nikula

2

3 Report 3 Raportti 3 THE BaRE METHOD Version 1.0 Uolevi Nikula Lappeenranta University of Technology Department of Information Technology P.O. Box 20 FIN Lappeenranta ISBN ISSN Lappeenranta 2002

4

5 The BaRE Method Version Uolevi Nikula Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this method internally. It may not be sold or used for commercial gain or other purposes without prior written permission. The BaRE method has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The method is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

6

7 Lappeenranta University of Technology The BaRE Method 1(1) PART 1: USING THE BaRE METHOD The BaRE Guide PART 2: THE BaRE TEMPLATES Requirements Document Template Appendix 1. Glossary Appendix 2. Typical Computer Configuration Appendix 3. Use Case Descriptions Appendix 4. Detailed Requirements Appendix 5. Rejected Requirements Interface Specification Template User Manual Template Requirements Change Document Template Appendix 1. Change Requests PART 3: BACKGROUND INFORMATION ON REQUIREMENTS ENGINEERING Practical RE in Short Appendix 1. Requirements Document Topics Survey <To be added: The Licentiate Thesis of Uolevi Nikula>

8

9 The BaRE Guide Version Uolevi Nikula Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The method is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

10

11 Lappeenranta University of Technology The BaRE Guide 1(33) Table of Contents 1 Introduction Practical Problem for the BaRE Method Design Principles The BaRE Elements Limitations of the Method How to Use This Guide Few Good Books on RE BaRE Method OVerview Quick Guide on Using the BaRE Method Requirements Document Template Requirements Development Requirements Development Process Process Overview Step 1: Establish objectives Step 2: Understand context Step 3: Organize knowledge Step 4: Elicit requirements Step 5: Prepare for problems Step 6: Prioritize requirements Step 7: Complete requirements document Step 8: Analyze requirements document Step 9: Validate requirements document Evaluation Process and Checklists Evaluation Process Requirements Document Pre-Review Checklist Requirement Pre-Review Checklist Requirements Analysis Checklist Requirements Validation Checklist Requirements Development Techniques Apprenticing Checklists CRUD Matrix Development Define System Boundaries Define the System s Operating Environment Diagram Development Document Studies Electronic requirements Interviews Introspection Meetings Prototyping... 23

12 Lappeenranta University of Technology The BaRE Guide 2(33) Reading Reuse Requirements Reviews Scenario Development Two-Level Approach to Requirements Documenting Write User Manual Requirements management Change Request Process Requirements Management Techniques Baselining Change Management Version Identification Maintain Change History Tool Support Training Glossary References... 33

13 Lappeenranta University of Technology The BaRE Guide 3(33) 1 INTRODUCTION 1.1 Practical Problem for the BaRE Method 1.2 Design Principles RE is often considered as the hardest part of software system development since it makes fundamental decisions about the system when the least is known about the system. The additional fact that late changes in requirements can have huge cascading effects in the whole development effort make the requirements phase even more difficult phase. Still it is reported that more than 75% of all enterprises have deficient RE practices. The practical RE problem has been known for a long time and the current name for the area requirements engineering was also suggested already 26 years ago. The research efforts during this time have come up with a number of different approaches to RE: standards, generic processes, good practice guides, and comprehensive methods. Despite all these efforts the gap between research and practice seems to persist. It must be noticed that the situation has changed a lot during the past decade. For example, there are already tens of books on RE many of which are targeted for practitioners and in 2002 alone there were at least three new books published in RE. However, this wealth of activities and literature does not seem to have affected the situation in industry by and large. Thus a new method was developed that approaches this problem in a fundamentally different way. This method is called BaRE (basic RE). The BaRE method design was based on five key requirements. These requirements are as follows: 1. ready to use, 2. simple, 3. domain specific, 4. adaptable, and 5. systematic approach to RE. From these only ready to use and adaptable are base requirements while simplicity and domain specificity are actually properties supporting the ready to use requirement. The systematic approach is a general requirement that seemed worthwhile to include in the requirements set. A ready to use method entails actually three requirements: the method is available for the user when it is needed, it allows the user to focus on the software development problem at hand, and it is proven useful in practice. It has been found that the quality of tools and techniques for RE have been inadequate in many cases in practice. This leads quite often

14 Lappeenranta University of Technology The BaRE Guide 4(33) to a situation where the user becomes bogged down with the intricate documentation and diagramming techniques that required by the method rather than focusing to the problem situation analysis. Method simplicity is central for a basic RE method since it can reduce the up-front investments in method adoption substantially. The costs of adopting a new method, when no purchases are required, are limited to the personnel training costs meaning that the simpler the method the lower the costs. This situation is also reflected in practice where companies with immature RE focus in informal and possibly semi-formal methods and find the most desirable property of RE techniques to be ease of use. The encountered difficulties with methods, on the other hand, vary a lot. In some cases poor documentation is blamed for the difficulties, in other cases companies are deterred by the huge size of the documentation, and also extensive training programs required for the method usage have been named as reasons to not use some method. To avoid at least some of these pitfalls the BaRE method was designed simplicity in mind. Domain specificity of the method is important for two reasons. Firstly, it has made it possible to increase the fit between the method and problem substantially to the point where the method can be called ready to use. Secondly, operating within one domain the applications and projects should possess fundamentally similar requirements which allows for reuse of the different artifacts, e.g. requirements documents and individual requirements, processes, etc. The key benefits of reuse in general include substantial productivity and quality improvements. It is also noteworthy that increasing the applicability of a method to different project and application types may make it progressively harder for systems developers to use the method. The need for method adaptability derives from the way companies use methods in practice. There are reports that 88% of companies using structured methods have customized the methods to their own needs. The fact that no two projects are alike leads to a situation where the infrastructure supporting the projects must also adapt to the different situations either by tuning the methods or by having different methods etc. available for different needs. It is good to notice that also people with different level of understanding in a domain have different needs for their methods. This means that people learning a new task need simple methods while experts need methods with different kind of properties, e.g. performance, capacity, adaptability, etc. The last requirement of systematic approach represents a free choice for the method. That is, an ad hoc approach may be even more efficient than any systematic one but since it is expected that software engineers will be supported it appears natural to follow an orderly engineering approach. It also seems that a simplified step-by-step approach suits to

15 Lappeenranta University of Technology The BaRE Guide 5(33) 1.3 The BaRE Elements people learning a new method well since it should make following the method easier and, on the other hand, it should make detecting deviations from it easier since straightforward steps are provided. The key elements, or constructs, for the BaRE method are as follows: 1. requirements document template, 2. requirements development activity, 3. requirements management activity, 4. tool support for requirements management, and 5. training. The first construct in BaRE is a requirements document (RD) template. This construct was selected as the starting point for the method development since in most cases it appears to serve as the first step in improving RE practices. This is also reflected by the fact that it is among the oldest and best documented, i.e. standardized, elements of RE. In practice the RD related practices have been found to be surprisingly immature. This finding is well in line with a more general finding that 85% of all enterprises have inadequate software documentation methods. These findings are quite shocking when the roles of a RD are considered. These include the following ones: A basis for software development contracting. A basis for external reviews. Reuse in other projects. A standard medium to communicate about requirements between customers, users, managers, and developers. The requirements development activity serves as the second BaRE construct. It consists of the requirements elicitation, analysis, documentation, and validation tasks which means that it is the activity that should solve the hardest part of software development problem figure out what should be done and document it for the development team. A formal end of the requirements development activity is the baselining of the RD. However, since the requirements change and new releases of software are needed, in practice new RD versions may also be produced in another requirements development phase. The third construct is the requirements management (RM) activity. RM begins with a baselined RD and keeps the changes under control during the rest of the software development. The division between requirements development and RM is somewhat arbitrary and the success of either activity without the other has been questioned. However, since the emphasis, or most effort, is spent in different kind of tasks division to these two phases does make sense.

16 Lappeenranta University of Technology The BaRE Guide 6(33) The fourth construct is tool support for RM. Use of tools to support RM appears to be unanimously encouraged in literature and this situation reflects the experiences from the practice. Even if small projects may manage without tool support in the case where more requirements, or change requests, are filed and should be resolved on tight schedules manual operations tend to get into trouble. It is, of course, totally case dependent decision when tool support is needed. The fifth and last construct is training. The real topic behind training is the need for skilled personnel and supporting the development of the knowledge and understanding required from real experts. The understanding of a method can be classified in three levels where the first level users learn the method by following it literally. The second level users have passed this stage and are more interested in finding the limits of the method and thus experiment with it more. The last level of users is the expert level where the use of some specific method has no meaning anymore these experts can judge the situation at hand and have the understanding and skills to solve it in appropriate manner using the available tools. Such a classification is useful from the method development point of view since different level of users need different kind of training or support. The classification also makes it clear that first level users need clear instructions on the steps to take to complete the task at hand, second level users want to experiment with new techniques etc. and third level users may just take a look at some interesting topics to find new tools to their toolboxes. The justification for selecting the previous items as the key constructs follows from the interconnections they have with each other. Namely, all these five constructs are important parts of an RE method adoption and addressing any single construct may appear useless in the absence of some other construct. For example, adopting only a RD template leaves users wondering how to actually complete it a problem that is addressed by the requirements development construct. Adopting a requirements development method, on the other hand, may prove of little use unless the limits of it are known with a decent general understanding of RE which is the goal of the training. Even a RD template and a requirements development method with appropriate training may fall short in practice unless requirements management suggesting and handling changes is also addressed. And finally in any project of little more size there is a risk that so many requirements and change requests are proposed that managing them manually becomes an impossible task and tool support for RM is needed. This set of relationships between the constructs is not an exhaustive one but should demonstrate the need to address all the constructs simultaneously which is obviously a big challenge. However, the requirements for the method especially ready to use supported by simplicity and domain specificity should allow

17 Lappeenranta University of Technology The BaRE Guide 7(33) 1.4 Limitations of the Method addressing each of the constructs sufficiently to provide their main benefits. The BaRE method is designed for small projects developing administrative and business applications. The primary constraint on the project size is that one requirements engineer is sufficient for the project. In practice this means projects with a duration of six to twelve months, less than half a dozen workers, and less than a 100 keur budget. This is not a hard limit and does not exclude co-operation but it makes one person responsible for developing and managing the requirements. With this limitation elimination of the problems caused by multiple persons working parallel on the same project is possible. Specifically the expected issues to avoid include inconsistent and contradicting requirements, requirements omissions, simultaneous working on same requirements, and a need for a complex RM tool. As a RE method this method is applicable throughout the software lifecycle including both development and maintenance phases. However, it focuses on requirements and explicit linkage to design or other phases is not designed for. Finally, due to the documentation of requirements it is evident that a project should possess some stability regarding its requirements to avoid extraneous work in maintaining them. Technically the method focuses on semi-formal methods. There are no restrictions for using informal or formal methods but neither are they supported in any way. Despite the obvious need for a RM tool developed with the basic RE requirements in mind BaRE does not have any automated tool to support yet. The only support in addition to the documentation is the requirements document templates. The user level of expertise can be characterized with the three levels mentioned in Section 1.3 (The BaRE Elements). In the case of BaRE the decision was made to target the method for the first level users and supplement it with information that should prove useful for second level users and possibly even for the third level users. This approach reflects the results of the state of the practice surveys where the RE practices and knowledge in RE techniques as well as in RM are in general found weak. The following topics have also been reported as important for the success of RE: resource allocation, organizational issues, and maintaining good relations with customers. Even if resource allocation has been found as a significant factor for RE success, project management and resource allocation have been excluded from the method to keep it focused on RE. Similarly organizational issues have been reported to affect systems development efforts but the lack of proven (i.e., ready to use) solutions precluded addressing them in the

18 Lappeenranta University of Technology The BaRE Guide 8(33) 1.5 How to Use This Guide 1.6 Few Good Books on RE BaRE method. And finally it was considered wise to leave the problem of maintaining good relations with customers to the personal skills of the requirements engineer. This BaRE Guide explains the use of the BaRE method. It is supplemented with a requirements document (RD) templates and Practical RE in Short guide. Practical work with the BaRE method is expected to start with the RD template. This guide includes the requirements development process that explains how the RD template is planned to be completed in an orderly manner. This guide explains also the requirements management (RM) practices and suggests processes for change management and evaluation processes. Thus this guide works as the training material for the BaRE method. A wider perspective to RE is provided in the Practical RE in Short guide. This guide provides more background information on RE and contains a reasonably wide bibliography on RE literature. The BaRE method was constructed so that following it the adopter can learn by doing and benefit from the orderly RE from the beginning. However, it is expected that after running a few projects with BaRE needs arise to develop the RE practices further. Even if BaRE does provide suggestions on how to extend the method it is evident that at some point more traditional process improvement will take over the BaRE method. The books on RE in this guide limit to the ones that proved most useful in the method construction phase. These books are listed in Table 1 with short description of each book.

19 Lappeenranta University of Technology The BaRE Guide 9(33) Table 1. Few good books on RE and their descriptions. Book Kotonya and Sommerville 1998 Kovitz 1998 Lauesen 2002 Leffingwell and Widrig 1999 Robertson and Robertson 1999 Sommerville and Sawyer 1997 Wiegers 1999 Approach to RE Introduction to RE Example methods for RE Requirements document, content and style manual Styles and techniques to do RE Many requirements document examples Overview of RE activities Includes a recipe to get started with RE A generic process for RE Good practices for RE Software process improvement Good practices for RE 2 BARE METHOD OVERVIEW Figure 1 provides a general view on the BaRE method and its fundamental parts. Requirements Document Template 1.2 Business Goals ID Description Examples Speed up invoicing Reduce IT costs Observe deadlines BaRE Guide Requirements Development Process Step 1: Establish objectives RD Topics Participants Initiator of... Techniques Tasks 1. Interview initiator... Step 2:... Techniques Introspection... Document review... Negotiation meeting Requirements Management Change management Evaluation process... Checklists Requirements analysis Requirements validation... Figure 1. The BaRE method. The method targets for developing a requirements document and thus it includes a RE template. The BaRE Guide includes the instructions on how to define the contents of the RD by suggesting a requirements

20 Lappeenranta University of Technology The BaRE Guide 10(33) development process. The process description consists of nine steps that provide guidance for a requirements engineer working on the RD. This guidance consists of RD topics to address in each step, people to involve and techniques to use in the step, and also tasks to perform in each step. Further the requirements development techniques are described in short in the guide and initial checklists are suggested for various tasks in the process. Since the BaRE divides RE in the principle phases requirements development and management the management phase is also addressed in the guide. However, since the tasks in RM phase vary quite a bit from the requirements development phase, its structure in the guide is a little bit different. 3 QUICK GUIDE ON USING THE BARE METHOD This section provides short instructions on adopting the BaRE method in an organization, adapting the method to project specific needs, and how to actually use the method in a project. However, first a general approach to RE improvement effort with the BaRE method is suggested. The first step in initiating a RE practice improvement effort is to assign the role of a requirements engineer to some person. This role assignment has two purposes: first it makes this person responsible for learning RE and collecting information on it and second it gives him/her the right to invest both time and money on these tasks. Thus, in the long term, this principle requirements engineer should develop an organizational knowledgebase on RE books, articles, templates, tools, etc. in addition to his/her own experiences that others in the organization can utilize on need. Another key task for this requirements engineer is to lead the adoption of new methods to the organization and help in evaluating their fit to specific projects. In the case method adaptation is needed this should also be assisted by the principle requirements engineer both to utilize his/her knowledge and increase them with this new adaptation experience. Adoption of the BaRE method in an organization should start with a review of the BaRE Guide for a general fit to the problem domain and organization specific terminology. Due to the domain specificity of BaRE the fit with the problem domain should be fairly good from the beginning. In the case where the method seems to require extensive modifications one should consider whether to continue with BaRE or look at other alternatives. There is nothing to inhibit even major modification to BaRE, but such actions should be left for experienced requirements engineers since they go beyond the key property of ready to use. If, on the other hand, the method appears to match the problem domain well one should continue with the terminology comparison. The fact that RE terminology is far from a standardized one makes it important to prepare even for

21 Lappeenranta University of Technology The BaRE Guide 11(33) major discrepancies in the terms. After these two initial comparisons and possible adaptations the BaRE method is ready to project level use in the organization. Each project should first evaluate the fit of BaRE to their specific needs. This comparison is done in two phases firstly, the problem domains of the project and the method should be considered and then the need for project specific adaptation should be assessed. The need for another problem domain comparison is due to the possibility that the organization may run very different kinds of projects (e.g. time critical, small, large, etc.) in very different kinds of problem domains (e.g. real time, life critical, and business information system domains). The project specific needs should be limited to fairly small adaptations of the method. The most common tasks should include adding an attribute or two to the requirements (i.e., a column(s) in RD template) or usage of the detailed requirements appendix due to multiple attributes for each requirement, decision to use other appendices, possible elimination of RD topics or addition of new ones. Since the current RD templates and the requirements development process are synchronized adding or deleting RD topics leads to a need to modify also the requirements development process. The elimination of RD topics can be done in two ways either by deleting the respective section from the RD or adding some specific tag in the heading. One common way to tag the unused sections is to add N/A (not applicable) to the heading. This approach should be used if the organization has adopted a standard RD template to be able to identify omitted topics from the RD easier. The tagging approach may also prove useful if the RD contents is not yet quite clear since recovering the deleted sections is much easier this way. In the case the RD template appears to lack a place for some important topic it should be added to the template. The Practical RE in Short guide includes as an appendix a table that contains topics from eight different RD templates. This comparison table can be used to find missing topics from the BaRE template. The actual method usage is quite straightforward since the processes are synchronized with the documents they are intended to produce. They also provide tasks to complete, people to involve, and techniques to use lists for each step. Thus the key steps in adopting XP fit quite well also for requirements engineers starting to use the BaRE method: 1. Do everything as written. 2. After having done that, experiment with variations in the rules. 3. Eventually, don t care if you are doing XP [BaRE] or not. One important point about BaRE is the two level documentation. This means that the actual RD is expected to be used in all projects to document the central requirements in a compact way. However, in some

22 Lappeenranta University of Technology The BaRE Guide 12(33) 4 REQUIREMENTS DOCUMENT TEMPLATE cases more complete documentation may be preferred and BaRE provides five different appendices for this situation. It is suggested that the first projects use only the RD template. This smooth transition from an undocumented culture to a more comprehensive documentation is suggested to avoid getting lost in developing a very comprehensive documentation set that nobody will read anyway. Experimenting with different alternatives will teach the right level of documentation, but it is assumed, though, that neither no documentation at all nor documenting all the aspects of every detail in the software is the right approach. The BaRE requirements document (RD) template covers three documents with five appendices. In addition to the actual RD template there are templates for interface specification and user manual. All the appendices belong to the actual RD template and they are glossary, typical computer configuration, use case descriptions, detailed requirements, and rejected requirements. The RD template set was developed based on literature surveys and good practices suggested for requirements documenting. The actual RD template contents were derived from a survey with eight well known RD templates. Even if these templates did have much in common they also deviated quite much from each other. For the BaRE RD template the topics that seemed most relevant for small administrative and business applications projects were selected. Another key selection criteria was that the RD template focused on RE and thus, e.g., many topics related to project management were omitted from the surveyed templates. The table showing the topics from this survey can be found as an appendix to the Practical RE in Short. The reason to have three different documents in the RD set is the different purposes these documents serve. The actual RD (the first level documentation) is intended to serve as the central RD documenting the requirements in a concise way and in a form that both customers and developers find understandable. The interface specification, on the other hand, is intended to supplement the actual RD with developer specific topics. Such topics include detailed user, system, and communication interface specifications, system users that are needed to maintain the system (i.e., system administrators, operators), detailed implementable data models, and CRUD matrix. The user manual is among the first prototypes of the system that both customers and developers should review, but since it should evolve to a real deliverable of the project it is developed on its own from the beginning. The interface specification and the user manual with the RD appendices form the second level documentation.

23 Lappeenranta University of Technology The BaRE Guide 13(33) 5 REQUIREMENTS DEVELOPMENT 5.1 Requirements Development Process Process Overview All the five appendices are optional and should be attached to the actual RD if used. The appendices contain as well more detailed specifications (use case descriptions, detailed requirement descriptions) as more general documents serving as organizational memory (glossary, typical computer configuration, and rejected requirements). The comprehensive documentation set forms a two level documentation for the BaRE method. Such a large set of documents are provided so that different needs of the adopters can be addressed. However, it is assumed that all the documents are used very rarely if ever. The two level documentation set means that the primary means of documenting requirements is the use of the actual RD template. In the case more complete documentation is needed, the other second level templates can be used selectively. For projects that do not have experiences from developing and using requirements documents before it is suggested that only the actual RD is developed. Developing additional documents may be beneficial, too, but developing a very extensive set of documents may deter all the other participants in the project from them. Thus, especially when documents have not been developed before, gradual introduction of documents may prove beneficial. This approach allows also for the requirements engineer to experiment and find the suitable level of documentation for organization in question. This chapter discusses the requirements development and evaluation processes and explains the requirements development techniques in short. The nine steps forming the kernel of the requirements development process are presented in this section. These activities are called steps to suggest that people new to requirements development should follow these activities in the given order. With experience the order of the tasks and even their contents can be adapted based on the needs but in the beginning this straightforward approach is intended to ease the requirements development. The requirements development process consists of the following nine steps. 1. Establish objectives 2. Understand context 3. Organize knowledge

24 Lappeenranta University of Technology The BaRE Guide 14(33) 4. Elicit requirements 5. Prepare for problems 6. Prioritize requirements 7. Complete requirements document 8. Analyze requirements document 9. Validate requirements document Each step is described in more detail in the following sections. The RD topics for each step also suggest the order for developing them. The requirements engineer participates in all the tasks as the leader for the development effort Step 1: Establish objectives RD topics 1.1 Customer problem 1.2 Business goals 1.3 Stakeholders 1.4 Product purpose 1.5 Product position statement Participants Initiator of the development effort Stakeholders Techniques Introspection Document reviews Electronic requirements Interviews Negotiation meetings Tasks 1. Interview the initiator to get started with the task and to identify initial stakeholders 2. Review documents and introspect to get a good idea about the objectives 3. Interview stakeholders for deeper understanding of the task, use when appropriate 4. Do web searches to help develop the product position statement 5. Arrange meetings with all stakeholders to negotiate about common understanding of the objectives Step 2: Understand context RD topics 2.1 Product context System interfaces User interfaces Logical user interface characteristics

25 Lappeenranta University of Technology The BaRE Guide 15(33) Participants Techniques Tasks Operation types 2.3 Product Functions as use cases 2.4 Users Important domain properties Business process description 2.7 Constraints Initial Stakeholders Users Introspection Document reviews Electronic requirements Interviews Diagrams: context, workflow 1. Develop own understanding of the context, external interfaces, and the product in the defined context Step 3: Organize knowledge RD topics All the previously developed RD topics except for 2.8 Constraints, i.e and Participants Stakeholders Users Techniques Meetings, negotiation or review Tasks 1. Arrange meeting(s) to review named requirements document topics and to prioritize the business goals Step 4: Elicit requirements RD topics Participants 3.1 Performance requirements Initial 3.2 Data requirements 3.3 Software system attributes Initial Documentation requirements Miscellaneous requirements Initial App 2: Typical computer configuration App 2: Detailed requirements IS: 2. System interfaces IS: 3.x Dialog maps IS: 3.x User interfaces IS: 4. Refined data model IS: 5. Administrative users Stakeholders (including technical experts) Identified users

26 Lappeenranta University of Technology The BaRE Guide 16(33) Techniques Tasks Introspection Document reviews Electronic requirements Structured interviews Meetings: brainstorming, workshops, negotiation Prototypes, horizontal/user interfaces Diagrams: data model, dialog maps 1. Collect requirements from documents and individual people, use introspection 2. Broaden the requirements coverage with brainstorming session(s) 3. Deepen the requirements with use case workshop(s) 4. Narrow and prune the requirements, resolve conflicts with negotiation meetings Step 5: Prepare for problems RD topics 2.7 Constraints Final 2.8 Assumptions 2.9 Dependencies 3.1 Performance requirements Final 3.3 Software System attributes Final Miscellaneous requirements Final Likely changes Copyright, legal, and other notices 3.5 Design constraints Participants Stakeholders (including technical experts) Users Techniques Introspection Electronic requirements Structured interviews Meetings: brainstorming, negotiation, workshops Checklists Tasks 1. Try to uncover potential future problems with checklists 2. Verify availability of needed modules, components etc. with , web searches, and interviews 3. Arrange brainstorming sessions to broaden and define requirement categories Step 6: Prioritize requirements RD topics Apportioning of requirements Scope of initial release

27 Lappeenranta University of Technology The BaRE Guide 17(33) Participants Techniques Tasks Manual operations Restrictions, limitations and exclusions Stakeholders Users Introspection Electronic requirements Interviews Meetings, negotiation or workshops 1. Develop requirements allocation plan 2. Review and revise the plan in meeting(s) Step 7: Complete requirements document RD topics 1.6 Document overview 1.7 References All other topics in the document Participants Stakeholders Users Techniques Reading Personal review Tasks 1. Add references when you use them; at latest now 2. Validate the document personally 3. Complete missing sections Step 8: Analyze requirements document RD topics IS: 6. CRUD-matrix Participants Techniques Tasks Stakeholders Users Prototypes, vertical/technical Requirement analysis checklists Develop CRUD-matrix Negotiation meetings Step 9: Validate requirements document RD topics RD3-User Manual Participants Stakeholders 1. Develop CRUD matrix from data model and use cases 2. Analyze individual requirements with checklists 3. Develop prototypes and review them with users 4. Negotiate with stakeholders about possible problems, possibly by organizing meetings

28 Lappeenranta University of Technology The BaRE Guide 18(33) Techniques Tasks Users Prototypes, horizontal Checklists Review 1. Develop an initial user manual from the requirements document 2. Develop horizontal prototypes 3. Use checklists to validate requirements and the requirements document 4. Review the requirements document, user manual, and prototypes 5.2 Evaluation Process and Checklists Evaluation Process In this section an evaluation process is suggested for requirements and changed requests. Also a number of initial checklists are provided to support the requirements development process. The evaluation of requirements document follows the process described in Figure 2. The same process should be used also for individual requirements and change requests in the case they are evaluated and baselined. Evaluation item Pre-Review the item Plan the meeting Deliver the materials Meet for inspection Prepare individually Modify the item Conduct follow-up Baselined item Figure 2. The evaluation process, adapted from (Wiegers 1999) Requirements Document Pre-Review Checklist Standard contents/table of contents/structure Uses standard document conventions

29 Lappeenranta University of Technology The BaRE Guide 19(33) No empty placeholders or TBD s (to be defined) N/A (not applicable) used for unnecessary sections Check spelling Requirement Pre-Review Checklist Requirements Analysis Checklist Check both internal and external references Check that all used terms are defined Does each requirement have the company specified attributes defined An initial requirements analysis checklist (Sommerville and Sawyer 1997). Checklist item Description Premature design Does the requirement include premature design or implementation information? Combined Does the description of a requirement describe a single requirements requirement or could it be broken down into several different requirements? Unnecessary Is the requirement gold plating? That is, is the requirement a requirements cosmetic addition to the system which is not really necessary. Use of non-standard hardware Conformance with business goals Requirements ambiguity Requirements realism Requirements testability Requirements Validation Checklist Does the requirement mean that non-standard hardware or software must be used? To make this decision you need to know the computer platform requirements. Is the requirement consistent with the business goals defined in the introduction to the requirements document? Is the requirement ambiguous, i.e. could it be read in a different way by different people? What are the possible interpretations of the requirement? Ambiguity is not necessarily a bad thing as it allows system designers some freedom. However, it has to be removed at some stage in the development process. Is the requirement realistic given the technology which will be used to implement the system? Is the requirement testable, that is, is it stated in such a way that test engineers can derive a test which can show if the system meets that requirement? An initial requirements validation checklist, both for individual requirements and the requirements document (Sommerville and Sawyer 1997).

30 Lappeenranta University of Technology The BaRE Guide 20(33) Checklist item Completeness Consistency Comprehension Ambiguity Structure Traceability Conformance Description Are the requirements complete, that is, does the checker know of any missing requirements or is there any information missing from individual requirements descriptions? Are the requirements consistent, that is, do the descriptions of different requirements include contradictions? Are the requirements comprehensible, that is, can readers of the document understand what the requirements mean? Are the requirements ambiguous, that is, are there different possible interpretations of the requirements? Is the requirements document structured, that is, are the descriptions of requirements organized so that related requirements are grouped? Would an alternative structure be easier to understand? Are the requirements traceable, that is, are requirements unambiguously identified, do they include links to related requirements and to the reasons why these requirements have been included? Does the requirements document as a whole and do individual requirements conform to defined standards? 5.3 Requirements Development Techniques Apprenticing Checklists In this section the techniques included in the BaRE method are described in short with references to more complete descriptions. Apprenticing refers to the learning about a work by learning from the experts in the work. The basic activities include observing the master doing the work, asking questions about the work, and doing some of the work under the supervision of the master. This technique is especially suited for situations where interviews and meetings etc. do not appear to bring about the real content of the work. This may be due to the workers inability to explain their work or lack of time for it. More information about apprenticing can be found in the Robertsons (1999) book. Another interesting book on the topic is (Beyer and Holtzblatt 1998). A checklist collects a handful of central question for a topic in one place. The ideas is that when a task is considered complete, the questions in the checklist can be asked to verify that the most common issues are addressed in an acceptable way.

31 Lappeenranta University of Technology The BaRE Guide 21(33) CRUD Matrix Development Define System Boundaries There are three key characteristics for the checklists. Firstly, they are specific to some activity (e.g., requirements analysis, validation, review; RD contents, organization, style, quality, traceability, etc.). Secondly, each checklist should have at most about ten items. Having too many items in the list results in lost focus and vitiation of the checklist benefits. Thirdly, the contents of the checklists should reflect the currently most important issues in the organization. This means that the checklists should be updated periodically to keep the lists relevant. Both Wiegers (1999) and Sommerville & Sawyer (1997) provide a number of good initial checklists for RE. CRUD acronym stands for Create, Read, Update, and Delete operations. The CRUD matrix is used to associate each data element (as columns) of the system with a use case (as rows) by mapping each operation for every element to some use case. Missing operations for each element are recorded in the last row of the matrix. Thus CRUD matrix provides a way to analyze the system for missing data operations. More information on the CRUD matrix can be found in (Lauesen 2002). In the course of eliciting requirements it is wise to document practically all the requests the stakeholders have. However, in the early analysis phases it should be decided what is the system boundary so that the requirements can be allocated either to the system or outside of it. More information on the topic can be found in (Sommerville and Sawyer 1997) Define the System s Operating Environment Diagram Development The system s operating environment consists of the host computer for the system under development and the hardware and software systems with which the system is to interact. In addition to defining the environment, the expected changes in it during the system s life cycle should be considered. More information on the topic can be found in (Sommerville and Sawyer 1997). Diagrams visualize the system and should thus make it easier to understand some aspect of it. Since one diagram usually focuses on a specific aspect of the system, usually multiple diagrams should be

32 Lappeenranta University of Technology The BaRE Guide 22(33) Document Studies Electronic requirements Interviews developed to provide different views on the system. Example diagrams include context diagram, workflow diagram, data model, and dialog maps. The unified modeling language (UML) provides a number of diagrams for software development. The real benefit of UML is the de facto standard it is gaining as the notation for the drawings. With the wide use of the notation it is more likely that stakeholders already know the notation which smoothes the usage substantially. One book describing the UML is (Eriksson and Penker 1998). The BaRE method suggest the problem frame diagrams for context diagrams. These are explained in detail in (Jackson 2001). Document studies refers to the act of finding related documents and studying them to learn more about the subject at hand. Examples of possibly valuable documents include meeting memorandums, specifications (interface, protocol, etc.), user guides, requirements documents, reports, forms, etc. More information about document studies can be found in (Robertson and Robertson 1999) under name document archeology. Electronic requirements refers to using computer in the requirements elicitation. The key techniques include using to question about requirements and finding more information about a problem at hand with, e.g., web searches. The may prove indispensable in communicating with some stakeholders that are hard to get into meetings or reach by phone. Due to its asynchronous working people can reply to the questions when it fits them the best and even clarify some topics before replying. The web searches, on the other hand, may be used to find competing products, related standards, research reports, etc. that can shed light on some specific issues. More information about electronic requirements can be found in (Robertson and Robertson 1999). Interviews can be classified in two broad categories unstructured and structured interviews. Unstructured interviews refer to a free form discussion on some specific topic. They are quite often conducted as informal discussions on hallways etc. Structured interview starts by preparing a list of questions and going through this list with the interviewee to clarify the issues in the list.

33 Lappeenranta University of Technology The BaRE Guide 23(33) Introspection Meetings Prototyping More information about requirements studies can be found in (Leffingwell and Widrig 1999; Robertson and Robertson 1999; Lauesen 2002). Introspection is the most obvious technique for figuring out what the system should do to be successful. It refers to imaging what I kind of system I would want if I were doing that job. Thus, despite the fancy name, the technique is very common to every requirements engineer. More information on introspection can be found in (Goguen and Linde 1993) which discusses also a number of other requirements elicitation techniques. There are a number of different kind of meetings but for the BaRE method following four types of meetings are discussed: negotiation, review, workshop, and brainstorming. Negotiation meeting is the traditional meeting where agenda is distributed before, topics are discussed around a table, conclusions are drawn, and a memo written about the decisions. Review meetings are intended to present and discuss some work product in order to learn more about it and find problem in it. For more information see Section (Reviews). Workshop is a development oriented way of working together and should be used in, e.g., use case development. The flow of events is that someone prepares a preliminary use case list for the workshop and in the workshop new use cases are discovered, exceptions and scenarios are identified etc. The brainstorming meeting focuses on the early development phases when, e.g., the purpose of the product is still vague and a common vision for it is sought. Due to the purpose of inventing new ideas the brainstorming sessions are conducted in an atmosphere different from the other meeting types that are more problem solving oriented. More information about negotiation meetings can be found in (Sommerville and Sawyer 1997; Kotonya and Sommerville 1998; Lauesen 2002) and about workshops and brainstorming in (Leffingwell and Widrig 1999; Robertson and Robertson 1999; Lauesen 2002). Some of the key prototype types are horizontal, vertical, technical, and user interface prototypes. Horizontal prototypes are shallow in implementation and focus on describing the big picture of the prototyped area and consequently they are often used with user interfaces. This is, user interface prototypes show often only the dialogs etc. that are visible on the screen buttons etc. have often only line or two code behind and

34 Lappeenranta University of Technology The BaRE Guide 24(33) Reading Reuse Requirements no real functionality is provided. Vertical prototypes take another approach and implement some function in detail but as little as possible related functionality, and nothing that is not related to the function. Thus vertical prototypes are often used to solve technical question where it is not known whether the available technology, or skills, suffice to solve the problem at hand. Such problems could be, e.g., performance or capacity questions or connecting to some external system. It is also good to notice that prototypes can be executable or not which means that, e.g., user manual allows the reader to go through the system and get an idea of it even if no executable prototype were available. There is a lot of literature on prototyping, e.g. (Sommerville and Sawyer 1997; Leffingwell and Widrig 1999; Robertson and Robertson 1999; Wiegers 1999; Lauesen 2002). Reading is among the basic techniques that is often overlooked. In the smallest scale reading can be implemented by putting a document aside and reading it again after a few days or a week. More often that not one starts to wonder what the text tries to say and thus indicates need for refinement. In the case of having a team it is often more efficient to let others read the document and give feedback on it. This forms also the basis for document reviews (and inspections) where the material is distributed before the meeting and the participants study the material for the meeting to find problems in it. Due to the basic nature of the technique there is really not much literature on reading. However, literature on inspections and reviews (see above Meetings), or Personal Software Process (Humphrey 1995), do provide guidelines for reading. Operating in one domain should make reuse a viable option. That is, developing many applications for roughly the same purposes should lead to a situation where many requirements prove useful also in new applications. This, again, should result in less elicitation work, higher quality, and happier customers. Thus the potential for reuse should be considered after a few projects are run and a requirements database starts to grow to a useful size. More information on reuse can be found in (Sommerville and Sawyer 1997; Robertson and Robertson 1999; Wiegers 1999).

35 Lappeenranta University of Technology The BaRE Guide 25(33) Reviews Scenario Development In BaRE review meetings are intended to initiate a discussion forum about work products. Basically material is distributed before a meeting, participants study it to find problems in it, and the meeting is kept to discuss the problems. During the review problems are recorded and resolved at a later time. This is the basic flow of an inspection which works as the guideline for BaRE reviews, too. However, in the beginning the review meetings should concentrate more on discussing the material and to go through it which is the basic goal of walkthroughs. With more experience the shift to the direction of inspections is recommended. The inspections and walkthroughs that are the basis for BaRE review meetings are discussed, e.g., in (Leffingwell and Widrig 1999; Wiegers 1999; Lauesen 2002). One use case covers a number of scenarios which present the specific instances of a use case. For example, one use case scenario is the normal use case execution the happy day scenario where everything goes as planned. Different scenarios, then, present the various problems that can occur within a use case, e.g. a automatic teller machine is out of cash or paper for receipt. Developing such scenarios makes one think about all the possible problems and variations of the use case and thus results in a more complete model of the system usage. This creativity may also lead to a situation where feasibility of the scenario development gets questioned. Thus care should be exercised before rushing into scenario development. More information about scenarios and use cases can be found in (Sommerville and Sawyer 1997; Robertson and Robertson 1999; Wiegers 1999; Lauesen 2002) Two-Level Approach to Requirements Documenting The BaRE RD has two levels of documentation. The primary RD is supplemented with interface specification and user manual documents and five appendices. These appendices are glossary, typical computer configuration, use case descriptions, detailed requirements, and rejected requirements. The actual RD documents all the requirements in a concise way that is understandable by both customers and developers. In the case this approach appears insufficient, the appendices can be used for more detailed descriptions. The typical computer configuration and rejected requirements appendices, on the other hand, are used to as storage for

36 Lappeenranta University of Technology The BaRE Guide 26(33) Write User Manual 6 REQUIREMENTS MANAGEMENT 6.1 Change Request Process things that have been agreed upon some time and they are kept available to avoid reissuing the same questions at a later time. Since the actual RD is targeted also to the customers, the developers have the interface specification to document more technical topics for the development purposes. The user manual, on the other hand, is a project deliverable so it is kept aside throughout the whole software development effort as such. The reason a template for it is include in the BaRE method is to emphasize the need to start developing it already in the requirements phase. An initial user manual can serve as a prototype of the system to validate it even before any code is written. And even the act of writing how the system will be used forces to think about the tasks to complete and how they are actually done. More information about user manuals can be found in (Sommerville and Sawyer 1997; Wiegers 1999). In this section the BaRE requirements management practices are outlined. The BaRE method includes simple templates to record changes and change requests but these are only provided as a temporary aid to handle changes. The changes should be handled by the company standard change management system from where the requirements changes are directed to the requirements engineer and RM handles them further. In general a change request process consists of the following items (Wiegers 1999): 1. Entry Criteria 2. Tasks 2.1 Create Change Request 2.2 Evaluate Change Request 2.3 Make Decisions 2.4 Communicate Changes 3. Verification 4. Exit Criteria In BaRE the change request process is simple: change requests are recorded and evaluated after which accepted changes are implemented.

37 Lappeenranta University of Technology The BaRE Guide 27(33) 6.2 Requirements Management Techniques Baselining The evaluation process can be used both in evaluating the change requests and verification of the changes to requirements. In the literature only one relevant checklist item was found to the change request process. It is as follows: Does each change request have the company specified attributes defined. In this section the techniques for RM are described. The purpose of baselining is to differentiate between the requirements development and management phases. This line is often quite vague since requirements start to change as soon as they are defined and thus the requirements document is a changing document. The baseline works as a milestone that can be used as a formal reference, e.g., in contractual situations and to mark the start of the design phase. Use of the evaluation process for baselining is recommended to assure that all the stakeholders have a common understanding of the project and its current status. Figure 3 describes the boundary between requirements development and management.

38 Lappeenranta University of Technology The BaRE Guide 28(33) Marketing Customers Management requirements Analyze, Document, Review, Negotiate Requirements Development Requirements Management current baseline Baselined Requirements revised baseline Marketing, Customers, Management requirements changes Requirements Change Process project changes Project Environment Change Management Version Identification Figure 3. The boundary between requirements development and management (Wiegers 1999). More information on baselining can be found in (Wiegers 1999). Change management in general means that all the change should be handled in an orderly manner. It is suggested that all the change requests are handled through a single and standard mechanism in the company. Adherence to the standard mechanism makes it possible to track the changes as well as the time, effort and costs associated with them. BaRE suggests a skeleton for a change request process to start managing the changes with the goal of keeping the changes under control. In more advanced projects the change management process should also include impact analysis and cost estimation tasks. More information about change management can be found in (Kotonya and Sommerville 1998; Leffingwell and Widrig 1999; Wiegers 1999). Version identification consists of two parts: first the version number and then the status of the version. In the following these topics are discussed.

39 Lappeenranta University of Technology The BaRE Guide 29(33) Version numbering scheme for the requirements document is of the following form: Version +major-release+. +minorrelease+status+running-number, e.g. Version 1.0 Draft 1. In the case individual requirements need version numbers, the same scheme should be used. The major release number is an integer starting from 1 while the minor release number starts from 0. The distinction between minor and major releases is subjective but should reflect the importance of the changes. The running number after status is used to separate different intermediate releases of the document. The number is initiated to 1 after each status change and incremented by one when ever the document is modified after given it to someone. The requirements document statuses are listed in Table 2 and reflect the phase of the document in the evaluation process. A document is a Draft before it enters the evaluation process, Pre-Reviewed and Inspected during the process, and Approved after successful completion of the process. The requirements statuses and change request statues are shown in Table 2 and Table 3 respectively. Table 2. Requirement Document Statuses. Status Draft Pre-Reviewed Inspected Approved Definition The requirement document is under development. The requirement document has entered the evaluation process and pre-review has been conducted. The requirement document has been inspected but follow-up actions have not been implemented and verified yet. The requirement document has been verified after inspection and it is approved for development. Table 3. Requirement Statuses. Status Proposed Analyzed Approved Postponed Definition The requirement has been suggested by a source who has authority to provide requirements and it has been documented. The requirement has been analyzed, the needed attributes are elicited, possible conflicts have been resolved, and possibly needed negotiations with customer have been conducted. The requirement is approved and allocated to some release. The requirement has been postponed to a later release; an analysis is needed before subsequent evaluation.

40 Lappeenranta University of Technology The BaRE Guide 30(33) Implemented Verified Rejected The requirement has been implemented. The requirement implementation has been verified. The requirement has been rejected, rationale for the rejection has been documented Maintain Change History Tool Support The change requests have the same statuses as the requirements with one exception. The change requests also have an Installed status that is used after the product has been installed after the change. The analysis of each change request should also include impact estimation of the change to the project (low or high). More information on version identification can be found in (Wiegers 1999). Recording the changes and their rationale for each requirements helps in tracing the history of a requirement. This feature may prove useful, e.g., in audits or other situations where past events are needed. For this purpose the detailed requirements appendix includes a history field for the requirements. However, recording all the related data manually (date, time, author, ) may prove an unrealistic goal so tool support could help this task considerably. Also application and project type should be considered before rushing into the task. More information on change history can be found in (Leffingwell and Widrig 1999; Robertson and Robertson 1999; Wiegers 1999). BaRE method does not have special tool support available. Some tools that could be used to support the RE tasks include: Microsoft Word, MS-Excel, MS-Access SmartDraw (smartddraw 2002) Freeware tools for RM include currently at least: sfrm, C.A.R.E, and REM (sfrm 2002; SOPHIST Group 2002; Toro 2002). More general information about tools to support RM can be found in (Sommerville and Sawyer 1997; Kotonya and Sommerville 1998; Wiegers 1999).

41 Lappeenranta University of Technology The BaRE Guide 31(33) 7 TRAINING BaRE method is designed to make it possible to learn by doing and consequently reduce the up-front costs of adopting the method. A software engineer with practical experiences from RE can probably start using BaRE after going through this guide. However, the first few projects can be assumed to require some extra time to learn to use the suggested techniques etc. in an efficient way. The situation could be smoothed a lot with a few days course in RE. In the long term it would be beneficial for the whole software development team to possess basic understanding of RE. The engineers not participating in requirements development or RM actively would probably benefit most from a one day seminar on the topic. For the active requirements engineers a one week course might be more suitable. However, in the case these are not available, studying the BaRE documents should provide an overview of the key topics. In the case of questions, however, it would be good to arrange for specialist support in the form of consultation. One form of internal training is the development of glossary for the application domain. The purpose of glossary is to clarify special terms and the ones that may have different interpretations in the application domain and in common usage. More information about training can be found in (Wiegers 1999).

42 Lappeenranta University of Technology The BaRE Guide 32(33) GLOSSARY RE RM RD XP CRUD TBD N/A CCB Requirements Engineering Requirements Management Requirements Document extreme Programming Create, Read, Update, Delete (operations) To Be Defined Not Applicaple Change Control Board

43 Lappeenranta University of Technology The BaRE Guide 33(33) REFERENCES Beyer, H. and K. Holtzblatt (1998). Contextual Design: Defining Customer-Centered Systems. San Francisco, CA, Morgan Kaufmann. Eriksson, H.-E. and M. Penker (1998). UML Toolkit, John Wiley & Sons. Goguen, J. A. and C. Linde (1993). Techniques for Requirements Elicitation. IEEE International Symposium on Requirements Engineering. pp Humphrey, W. S. (1995). A Discipline for Software Engineering. Reading, Massachusetts, Addison-Wesley. Jackson, M. A. (2001). Problem Frames: Analyzing and Structuring Software Development Problems, Addison-Wesley. Kotonya, G. and I. Sommerville (1998). Requirements Engineering: Processes and Techniques. Chichester, John Wiley & Sons. Lauesen, S. (2002). Software Requirements - Styles and Techniques. Harlow, Addison-Wesley. Leffingwell, D. and D. Widrig (1999). Managing Software Requirements: A Unified Approach. Reading, Massachusetts, Addison-Wesley. Robertson, S. and J. Robertson (1999). Mastering the Requirements Process. Harlow, England, Addison-Wesley. sfrm (2002). Software for Requirements Management. June 17, smartddraw (2002). SmartDraw.com. September 24, Sommerville, I. and P. Sawyer (1997). Requirements Engineering: A Good Practice Guide. Chichester, England, John Wiley & Sons. SOPHIST Group (2002). SOPHIST - Group for Innovative Software Engineering Ltd., SOPHIST Group. September 25, Toro, A., Durán (2002). REM main page. September 25, Wiegers, K. E. (1999). Software Requirements. Redmond, Washington, Microsoft Press.

44

45 Requirements Document for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Document Issued Document Version 1.0 Document Status Accepted Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

46

47 Lappeenranta University of Technology Requirements Document 1(16) Accepted Confidential CHANGE HISTORY Date Version Description Author Created document Un Removed Viewpoints topic as irrelevant Un Changed all ID field names to ID-only Un Added Table Text text style Un Added examples as hidden text Un Added missing tables Un Changed SC (Snow Card) field name to DR (Detailed Requirement) Un Removed Change-appendices to their own documents Removed Data Dictionary from appendices for now Added App 5: Rejected Requirements Un Footer translated to English Un D1 Changed versioning scheme Un D1 Removed Status column from Appendices table, no need anymore D1 Reordered contents to reflect the process Un D1 Added table for UI logical characteristics Un D2 Added examples, minor restructurings Un D3 Started using a cover page Un A Accepted the document Un Un Un Un TABLE OF CONTENTS Change History... 1 Table of Contents Introduction Customer Problem Business Goals Stakeholders Product Purpose Product Position Statement Document Overview References Overall Description... 5

48 Lappeenranta University of Technology Requirements Document 2(16) Accepted Confidential 2.1 Product Context Product Perspective System Interfaces User Interfaces Logical User Interface Characteristics Operation Types Product Functions as Use Cases Users Problem Domain Description Important Domain Properties Business Process Description System Requirements Allocations Apportioning of Requirements Scope of Initial Release Manual Operations Restrictions, Limitations, and Exclusions Constraints Assumptions Dependencies Specific Requirements Performance Requirements Response and Processing Times Precision Capacities Data Requirements Database Data Model Software System Attributes Reliability Availability Security Maintainability Supportability Portability Usability Scaleability Other Nonfunctional Requirements Documentation Requirements Miscellaneous Requirements Likely Changes Copyright, Legal, and Other Notices Design Constraints... 16

49 Lappeenranta University of Technology Requirements Document 3(16) Accepted Confidential APPENDICES Appendix Date Version 1: Glossary 2: Typical Computer Configuration 3: Use Case Descriptions 4: Detailed Requirements 5: Rejected Requirements

50 Lappeenranta University of Technology Requirements Document 4(16) Accepted Confidential 1 INTRODUCTION 1.1 Customer Problem 1.2 Business Goals <Rationale for the new product, short history and events leading to the development of the new product.> <Business goals that justify the purchase/costs of the software, expected benefits, savings, etc.> ID Description DR G1 Y/N Replace outdated platform Integrate order documents and database Use experience data for quotation Support systematic marketing Faster capture of cost data Speed up invoicing Reduce IT costs Remove error sources Observe deadlines Reduce over- and undertime payment Improve roster quality We cannot do (survive) without it 1.3 Stakeholders ID Stakeholder Type Description Responsibilities ST1 <Stakeholder examples > End-users of the system Customers Developers (design, coding, testing, documenting, quality assurance) Maintenance staff (backups, restoring, bug fixes, enhancements, changes) External bodies: regulators, certification authorities Management, project sponsor Business subject matter experts Technology people

51 Lappeenranta University of Technology Requirements Document 5(16) Accepted Confidential 1.4 Product Purpose Marketing people Product managers Lawyers Usability experts Professional bodies 1.5 Product Position Statement 1.6 Document Overview 1.7 References <Problem to be solved with the software> <Product position statement fits to products but is not as suitable for bespoke system development projects> For <target customers> Who are dissatisfied with Our product is a That provides Unlike We have assembled <the current market alternative> <new product category> <key problem-solving capability, that is, compelling reason to buy> <primary competitive product alternative> <key whole product features for your specific application> <Who/roles should read which parts of the document, where to find different kind of information> Reader Type Sections to Read Manager/Designer/Tester/Customer/ <List of other documents providing more detailed information> 2 OVERALL DESCRIPTION 2.1 Product Context <Context diagram with Jackson2001 notation>

52 Lappeenranta University of Technology Requirements Document 6(16) Accepted Confidential Periods & ranges a c Nurses' station Monitor machine Medical staff b e Analog devices f ICU patients a: Period, Range, PatientName, Factor b: EnterPeriod, EnterRange, EnterPatientName, EnterFactor c: Notify e: RegisterValue f: FactorEvidence 2.2 Product Perspective Figure 1. Patient monitoring annotated context diagram System Interfaces ID Description IS S1 Y/N <Examples of system interfaces> Software: purchased components, reused components, common components Hardware that must be supported by the software Communications interfaces: LAN, WLAN, modem User Interfaces ID Description IS I1 Y/N <Examples of user interfaces> Dialogs: main, login, search, error, start up (splash), save, open, close, replace, send, print, print-preview, change password, change font, options, Logical User Interface Characteristics ID Description IS L1 Y/N Required screen formats

53 Lappeenranta University of Technology Requirements Document 7(16) Accepted Confidential Page or window layouts Contents of any reports or menus Availability of programmable function keys Operation Types ID Description DR O1 Y/N Regular Degraded Maintenance Training Emergency Alternate-site Peacetime Wartime Ground-based Flight Active Idle Backup 2.3 Product Functions as Use Cases ID Name UCD UC1 Y/N Update weather forecast Monitor untreated roads Record treated roads Produce de-icing schedule Record truck changes Record weather station readings Amend de-icing schedule Identify faulty weather station Record new weather station Record road

54 Lappeenranta University of Technology Requirements Document 8(16) Accepted Confidential 2.4 Users ID User Type Count Skill Level US1 Use Pattern Represe nted by Prior ity <Examples of user types> Chemists Buyers Chemical stockroom staff Health and safety staff School children Road engineers Project managers 2.5 Problem Domain Description Important Domain Properties ID Description DP Business Process Description <Examples of domain properties, i.e. external factors that have an effect on the product, but are not mandated requirements constraints> One ton of de-icing material will treat 3 miles of single lane roadway. Drivers cannot work more than three hours without a break. The existing application is 10,000 lines of C code. <E.g. UML activity diagram>

55 Lappeenranta University of Technology Requirements Document 9(16) Accepted Confidential Wait for event Take up reservation customer arrives/ enquiry/ cancel request/ [else] Check availability [suitable room] amendment request/ Cancel reservation no-show/ Make reservation Amend reservation Confirm reservation Process no-show Notify billing system Figure 2. Business process for hotel reservation. 2.6 System Requirements Allocations Apportioning of Requirements <Requirements criticalities and precedences> Scope of Initial Release <Tasks, features, or use cases that are implemented in initial version> Manual Operations <Operations that need to be done but are not supported by the software> Restrictions, Limitations, and Exclusions <Properties that have been allocated to a specific future release etc.> 2.7 Constraints ID Description DR C1 Y/N Regulatory policies Hardware limitations

56 Lappeenranta University of Technology Requirements Document 10(16) Accepted Confidential Parallel operation Audit functions Control functions Higher-order language requirements Signal handshake protocols Criticality of the application Current Implementation Environment Partner Applications Commercial Off The Shelf Packages Anticipated Workplace Environment Schedule Constraints Financial Constraints Price Constraints Safety Requirements 2.8 Assumptions ID Description DR A1 Y/N <Example assumptions, i.e. things that are not facts but could affect the requirements stated in RD> Plan of using of commercial components (which) Issues related to development or operating environment 2.9 Dependencies ID Description DR D1 Y/N 3 SPECIFIC REQUIREMENTS <Example dependencies, if these are documented elsewhere, e.g. in project plan, refer to respective documents> Component x is developed by project y; x is on the critical path for this project Roads that have been treated will not need treating for at least two hours. Road treatment will stop at county boundaries. The Bureau s forecasts will be transmitted according to their specification issued by their engineering department. 3.1 Performance Requirements ID Performance Requirements DR

57 Lappeenranta University of Technology Requirements Document 11(16) Accepted Confidential P1 Y/N The product shall schedule such that the minimum necessary amounts of de-icing material are spread on roads. The product shall schedule such that the rescheduled de-icing truck is estimated to arrive at the breakdown location within 30 minutes of breakdown notification Response and Processing Times ID Response and Processing Times DR RP1 Y/N 95% of catalog database queries shall be completed within 2 seconds on a 450 MHz Pentium II PC running Microsoft Windows 2000 with at least 50% of the system resources free. (Notice that having a standard PC defined in appendix you would not need to state it here anymore.) 95% of the transactions shall be processed in less than 1 s. Scrolling one page up or down in a 200 page document shall take at most 1 s. Searching for a specific keyword shall take at most 5 s. When moving to the next field, typing must be possible within 0.2 s. When switching to the next screen, typing must be possible within 1.3 s. Showing simple report screens must take less than 20 s. (Valid for 95% of the cases in standard load.) Precision ID Precision Requirements DR PR1 Y/N All the calculations will be done with 6 significant numbers. All the user interface fields for currency will show 3 digits after decimal period. The name field shall have 150 characters Capacities ID Capacity Requirements DR CA1 Y/N How many users will be online simultaneously on average How many queries will they likely run per day on average How many users will be online simultaneously on maximum

58 Lappeenranta University of Technology Requirements Document 12(16) Accepted Confidential 3.2 Data Requirements How many queries will they likely run per day on maximum The product shall use <16 MB of memory even if more is available Database Database Vendor Version User Count, Normal User Count, Max Database Size Data Model <E.g. UML class diagram with user visible classes only, including entities, attributes, and relations> Requester * Chemical Request requestnumber requestername chargenumber fulfillmentlocation submit() cancel() postpone() retrieve() * name employeenumber department roomnumber requestchemical() queryvendorcatalog() receivechemicalcontainer Request Line Information chemicalid vendorname quantity quantityunits add() delete() * 1 * Vendor Catalog vendorname chemicalid catalognumber containersizesavailable displayinformation() 1 Figure 3. Class diagram for part of the Chemical Tracking System.

59 Lappeenranta University of Technology Requirements Document 13(16) Accepted Confidential 3.3 Software System Attributes Reliability ID Description DR RE1 Y/N During the first week of operation at most 1 non-critical system failure is acceptable Availability ID Description DR AV1 Y/N System must be available for use xx.xx % of the time Mean time to repair after a failure is at most 1 hour Security ID Security Requirements DR SE1 Y/N Access to system must be controlled Access to information must be controlled Communications must be encrypted Data back up and restore is required Cryptographic operations must be done with algorithm x Logs and history data sets are needed Function x and y must be located in different modules Maintainability ID Description DR MA1 Y/N The supplier s hot-line shall analyze 95% of the problem reports within 2 work hours. Urgent defects (no work-around possible) shall be repaired within 30 work hours in 95% of the cases. When repairing a defect, related non-repaired defects shall be less than 0.5 on average. For a period of two year, the supplier shall enhance the product at a cost of per Function Point.

60 Lappeenranta University of Technology Requirements Document 14(16) Accepted Confidential Supportability ID Description DR SU1 Y/N The naming conventions in document x must be adhered to Installation of a new version shall leave all database contents and personal settings unchanged. Supplier shall station a qualified developer at the customer s site. Supplier shall deposit code and full documentation of every release and correction at Portability ID Description DR PO1 Y/N System must implemented using language x At most x % of the code can be host dependent At most x % of the components can be host dependent A particular compiler or language subset must be used A particular operating system must be used Usability ID Description DR UA1 Y/N A clerk typist grade 4 can do function X in Z min after 1 h of training A normal user can do all daily tasks x after 4 hour training A power user can learn all the daily tasks from the user guide in 4 hours Novice users shall perform tasks Q and R in 15 minutes. Experiences users complete tasks Q, R, and S in 2 minutes. 80% of users shall find system easy to learn. 60% shall recommend system to others Scaleability ID Description DR SC1 Y/N

61 Lappeenranta University of Technology Requirements Document 15(16) Accepted Confidential 3.4 Other Nonfunctional Requirements In the start up phase the system will have 10 users but it must support up to 1000 users during the first year of operation. <Any other non-functional requirements should be added here> ID Description DR NF1 Y/N Documentation Requirements ID Document Type Audience DO Miscellaneous Requirements ID Document Type Audience DO1 User Manual Printed/On-line All user types DO2 Installation Guide Printed/On-line System administrator DO3 Configuration Guide Printed/On-line System administrator DO4 Read Me file On-line System administrator <Any requirements that do not fit elsewhere> ID Type Description DR R1 Y/N Likely Changes ID Description When LC1 Our investigation into whether or not the new version of the processor will be suitable for our application is not yet complete. The government are planning to change the rules about who is responsible for de-icing the motorways, but we do not know what the changes might be Copyright, Legal, and Other Notices ID Description DR N1 Y/N Personal information must be implemented so as to comply with the Data

62 Lappeenranta University of Technology Requirements Document 16(16) Accepted Confidential Protection Act. The product must confirm with the disabled access laws. 3.5 Design Constraints ID Description DR DC1 Y/N Software must be written in Visual Basic The application must run on both our new and old platforms. Use the class library from Developer s Library on the corporate IT server. Compatibility with the legacy data base must be maintained. Use our C++ coding standard.

63 Appendix 1: Glossary for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Document Issued Document Version 1.0 Document Status Accepted Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

64

65 Lappeenranta University of Technology Appendix 1: Glossary 1(1) Accepted Confidential CHANGE HISTORY Date Version Description Author Created document Un Translated footer to English Un D1 Changed versioning scheme Un D2 Added abbreviations from RD Un D3 Started using a cover page Un A Accepted the document Un 1 INTRODUCTION 2 TERM DEFINITIONS <This glossary should be used initially as a data dictionary, too. That is, define terms in here, include data types, representation, format, accuracy, and range when possible. Once you feel comfortable with data definitions, move them to a dedicated data dictionary.> DR ID IS RD SC Snow Card UCD Detailed Requirement, used as column heading in RD to refer to detailed requirement description in Appendix 4. Identifier, used as column heading in RD. Interface specification, used as column heading in RD to refer to further information in another document.. Requirements Document See Snow Card Volere Snow Card, used to document requirements in detail. See Use Case Description Use Case Description Use cases are described in detail with a template in Appendix 3. Viewpoint An encapsulation of partial information about a system s requirements from a particular perspective.

66

67 Appendix 2: Typical Computer Configurations for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Document Issued Document Version 1.0 Document Status Accepted Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

68

69 Lappeenranta University of Technology Appendix 2: Typical Computer 1(1) Accepted Confidential CHANGE HISTORY Date Version Description Author Created document un Translated footer to English Un D1 Changed versioning scheme Un D2 Started using a cover page Un A Accepted the document Un 1 TYPICAL COMPUTER CONFIGURATIONS Item Property Config 1 Config 2 Processor Type Speed RAM Amount Display Size Resolution Hard Disk Capacity External Devices Keyboard Scanner Operating System OS Version Language User rights Operating Platform Type Version Language Concurrently running applications

70

71 Appendix 3: Use Case Descriptions for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Document Issued Document Version 1.0 Document Status Accepted Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

72

73 Lappeenranta University of Technology Appendix 3: Use Case Descriptions 1(2) Accepted Confidential CHANGE HISTORY Date Version Description Author Created document un Translated footer to English Un D1 Changed versioning scheme Un D2 Changed headings for use cases and added instructions Un D3 Started using a cover page Un A Accepted the document Un TABLE OF CONTENTS Change History... 1 Table of Contents <Use Case name> <USE CASE NAME> <Select either the simple template or the more comprehensive one from below, the simple one is from Cheesman & Daniels, UML Components, p.79 and the other one from Kulak&Guiney 2000, p.82> <Simple one> Name: Initiator: Goal: Main Success Scenario Extensions Variations <A Comprehensive Template> Use Case Name Iteration Summary

74 Lappeenranta University of Technology Appendix 3: Use Case Descriptions 2(2) Accepted Confidential Basic Course of Events Alternative Paths Exception Paths Extension Paths Trigger Assumptions Preconditions Postconditions Related Business Rules Author Date

75 Appendix 4: Detailed Requirements for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Document Issued Document Version 1.0 Document Status Accepted Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

76

77 Lappeenranta University of Technology Appendix 4: Detailed Requirements 1(2) Accepted Confidential CHANGE HISTORY Date Version Description Author Created document un Translated footer to English Un D1 Changed versioning scheme Un D2 Removed Viewpoint ID, changed name ID style Un D3 Started using a cover page Un A Accepted the document Un TABLE OF CONTENTS Change History... 1 Table of Contents Introduction Requirements Requirement <ID from RD> Requirement <ID from RD> INTRODUCTION <The detailed requirements template contents are adapted from the Volere Snow Card which is a copyright of Atlantic Systems Guild.> <Used for functional requirements, features, and any other detailed requirement, e.g. ones derived from use cases.>

78 Lappeenranta University of Technology Appendix 4: Detailed Requirements 2(2) Accepted Confidential 2 REQUIREMENTS 2.1 Requirement <ID from RD> Requirement Type Event/Use Case ID Description Rationale Source Fit Criterion Customer Satisfaction Customer Dissatisfaction Dependencies Conflicts Supporting Materials Status History 2.2 Requirement <ID from RD>

79 Appendix 5: Rejected Requirements for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

80

81 Lappeenranta University of Technology Appendix 5: Rejected Requirements 1(1) Department of Information Technology Confidential REQUIREMENTS ID Description Reason Who Date DR <ID: Identifier for the rejected requirement from the requirements document. Description: Short description of the requirement, possibly the requirement name. Reason: Why was the requirement rejected? Who: Who decided to reject the requirement? Date: When was the requirement rejected? DR: Detailed Requirements, Y means that detailed requirement description is found below in this document; N means that detailed description has not been defined.> DETAILED REQUIREMENTS DESCRIPTIONS

82

83 Interface Specification for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Document Issued Document Version 1.0 Document Status Accepted Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

84

85 Lappeenranta University of Technology Interface Specification 1(6) Accepted Confidential CHANGE HISTORY Date Version Description Author Created document Un Footer translated to English Un D1 Changed versioning scheme Un D1 Added interface ID s from RD Un D2 Added examples; tried to differentiate better examples, instructions, and template Un D3 Started using a cover page Un A Accepted the document Un TABLE OF CONTENTS Change History... 1 Table of Contents Introduction System Interfaces Interface to System <name> <ID> Interface to System <name> <ID> User Interfaces General User Interfaces Guidelines Dialog Map Window: <name> <ID> Overview Figure Window attributes Menu Bars Fields Window: <name> <ID> Refined Data Model Adminstrative users CRUD Matrix... 5

86 Lappeenranta University of Technology Interface Specification 2(6) Accepted Confidential 1 INTRODUCTION 2 SYSTEM INTERFACES 2.1 Interface to System <name> <ID> This document contains detailed external interface specifications for the PReMa software version 1.0. Section 2 covers system interfaces, Section 3 user interfaces, Section 4 describes the refined data model with internal structures, Section 5 describes administrative users, and Section 6 contains a CRUD matrix. <Example items to specify for each interface according to IEEE Std830> Name of item Description of purpose Source of input or destination of output Valid range, accuracy, and/or tolerance Units of measure Timing Relationships to other inputs/outputs Screen formats/organization Data formats Command formats End messages 2.2 Interface to System <name> <ID> 3 USER INTERFACES 3.1 General User Interfaces Guidelines <Collect here guidelines for user interfaces that should be applied to all screens, e.g. background colors for screen and controls, line colors, ways to indicate disabled controls, etc. For an example, see Kovitz 1998 p. 390>

87 Lappeenranta University of Technology Interface Specification 3(6) Accepted Confidential 3.2 Dialog Map <A dialog map showing where each dialog can be opened etc, example below from Wiegers 1999> OK; exit request function ask to place a request cancel entire request Confirm request is accepted Current request list submit request for >0 chemicals delete chemical from list cancel addition of new chemical select vendor and add to list Display error message invalid chemical ID OK Enter chemical ID to request request chemical from vendor request a different chemical List of vendors for chemical request chemical from stockroom request a different chemical select container and add to list cancel addition of new chemical List of stockroom containers ask to see container history return Container history 3.3 Window: <name> <ID> Figure 1. Dialog map for the Request a Chemical use case from the Chemical Tracking System Overview <Short description when the screen appears and what it is used for.>

88 Lappeenranta University of Technology Interface Specification 4(6) Accepted Confidential Figure Window attributes <Schematic figure with annotations> <Below an example table with few window attributes, Kovitz 1998> Attribute Value Resizable Yes Systems buttons Enter-key action Esc-key action Modal/modeless Close, minimize No effect, except when cursor is in a multi-line edit; then, inserts a new line. No effect Modeless Menu Bars <Below an example fragment from menu specification from Kovitz 1998> The Main window s menu bar contains the following items: Bug New Window Ctrl-W Opens a new Main window. Both windows operate simultaneously Separator Same as pressing the New Bug button in the Bug List. Grayed when New Bug is grayed. Edit Admin Undo Undo Last Edit Ctrl-Z See below (page ) See below (page )

89 Lappeenranta University of Technology Interface Specification 5(6) Accepted Confidential Fields <Below example table for field on a window, adapted from Kovitz 1998> Field name Current Query Description Shows: The text form of the current query; Or, if the current query is a saved query with a name different than its text from, shows: The saved name of the current query, in italics. See section x.y to find out how a query is translated into text from. Not editable; gray background. Examples: SPLNX Connectivity in text form. Master bug report A typical query, A saved query 3.4 Window: <name> <ID> 4 REFINED DATA MODEL <Data model in details, with internal structures> 5 ADMINSTRATIVE USERS 6 CRUD MATRIX User Type Count Skill Level Use Pattern Priority Administrative users <CRUD matrix refers to the Create, Read, Update, and Delete operations that usually should be performed to each entity in the data model. In the case of using use cases, CRUD matrix should match each

90 Lappeenranta University of Technology Interface Specification 6(6) Accepted Confidential entity with some use case for each operation. Missing operations can be marked in the last row of the table for further actions.> <Use cases> Missing operations <Entities from data model> <Create-Read-Update-Delete Operations as appropriate>

91 User Manual for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Document Issued Document Version 1.0 Document Status Accepted Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

92

93 Lappeenranta University of Technology User Manual 1(2) Accepted Confidential CHANGE HISTORY Date Version Description Author Created document Un Translated footer to English Un D1 Changed versioning scheme Un D2 Added cover page Un A Accepted the document Un TABLE OF CONTENTS Change History... 1 Table of Contents Introduction Introductory Guide to Software Functional Descriptions Installation Guide Error Messages and Recovery... 2 Glossary... 2 Index INTRODUCTION <Purpose and application area for the software.> 2 INTRODUCTORY GUIDE TO SOFTWARE <Short instructions for a beginner to get started with the software.>

94 Lappeenranta University of Technology User Manual 2(2) Accepted Confidential 3 FUNCTIONAL DESCRIPTIONS 4 INSTALLATION GUIDE 5 ERROR MESSAGES AND RECOVERY GLOSSARY INDEX <More detailed instructions on the software usage based on either the menu structure of the application or the tasks that are supposed to be completed with the application.>

95 Requirements Changes in PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

96

97 Lappeenranta University of Technology Changes 1(1) Department of Information Technology Confidential ChangeID Date Issuer Description Closed CR CH1 Y/N ID

98

99 Appendix 1: Change Requests for PReMa <The text conventions in this document are the following: Example text is shown in italics. Instructions, like this section, are shown in italics enclosed with < and > characters. When possible, examples and instructions are also marked as hidden text.> Product Name PReMa Product Version 1.0 Document Created Document Modified Project Name RETICE Confidentiality Confidential Customer tsoft Preparers un Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document template version 1.0 has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The template is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

100

101 Lappeenranta University of Technology Appendix 1: Change Requests 1(1) Department of Information Technology Confidential TABLE OF CONTENTS Table of Contents Change Requests <ChangeRequestName> <ID> Description Requirement <ID> Rationale Source Fit Criterion Dependencies Conflicts Supporting Materials Status History CHANGE REQUESTS 1.1 <ChangeRequestName> <ID> Description Requirement <ID> Rationale Source Fit Criterion Dependencies Conflicts Supporting Materials Status History

102

103 Practical Requirements Engineering in Short Version Uolevi Nikula Copyright 2002 by Uolevi Nikula. Permission is granted to use, modify, and distribute this document internally. It may not be sold or used for commercial gain or other purposes without prior written permission. This BaRE method document has been developed as a part of the licentiate thesis of Uolevi Nikula, Lappeenranta University of Technology, Finland, in conjunction with the tsoft technology transfer program of University of Joensuu, Finland. The method is currently under test use in tsoft projects and will be revised based on the experiences from industrial projects run under the tsoft program.

104

105 Lappeenranta University of Technology Practical RE in Short 1(47) Table of Contents Appendices 1 Introduction Requirements Engineering Overview Software Projects and Requirements State of the Practice in Requirements Engineering Basic Systems, Software, and RE Concepts Few Good Books on RE A Look at Software Process Improvement Requirements Document Templates Requirements Development Requirements Development Processes Evaluation Processes Checklists Requirements Specification Techniques Good Practices for Elicitation Good Practices for Documenting Good Practices for Analysis Good Practices for Verification Good Practices for Validation Requirements Management Good Practices for Requirements Management Change Management Tool Support Training Alternative Approaches to Requirements Engineering Glossary References Requirements Document Topics Survey

106 Lappeenranta University of Technology Practical RE in Short 2(47) 1 INTRODUCTION This Practical RE in Short guide accompanies the BaRE Guide by providing further information on RE. The information in this guide is intended to expand the understanding of RE and to provide examples in some cases. In a case more detailed information on specific topics is needed, references to appropriate literature are provided. Much of the information in Chapter 2 (Requirements Engineering Overview) is based on the licentiate thesis describing the BaRE method development effort (Nikula 2002). 2 REQUIREMENTS ENGINEERING OVERVIEW 2.1 Software Projects and Requirements In this section general topics on forming the foundations for RE and the BaRE method are discussed. The software projects have proven problematic to estimate and control in the past. The first study to really unveil the software project failures was The CHAOS Report that analyzed over 8,000 projects and estimated the total costs of the failures in the United States (US) in 1995 (The Standish Group 1995). We shall next take a closer look at The CHAOS Report and conclude this section with references to other reports underlining the importance of proper RE in software projects. The Standish Group published The CHAOS Report on the industry state in information technology (IT) development projects in US in It included 365 respondents representing 8,380 projects. The report estimated that in 1995 there were about 175,000 IT application development projects in the US using $250 billion. The American companies and government agencies were estimated to spend $81 billion for cancelled software projects and an additional $59 billion for projects that would be completed but exceed their original time estimates. The CHAOS Report divided the projects into three classes: successful, challenged, and impaired ones. The successful projects were completed on time and on budget with all features and functions implemented as initially specified. The challenged projects were also completed and operational but over budget, over the time estimate, and offered fewer features and functions than was originally specified. Finally the impaired projects were ones that were cancelled at some point during the development cycle. The overall success rate for the considered projects was only 16.2%, the challenged projects accounted for 52.7% of the projects, and the rest 31.3% of the projects were cancelled. For the challenged projects on average only 61% of the originally specified

107 Lappeenranta University of Technology Practical RE in Short 3(47) features and functions were available. One of the key reasons for the time and cost overruns was project restarts which means that a project is terminated prematurely and started again. In the study there were 94 restarts for every 100 started projects. However, this does not mean that almost every project had been stopped at some point since there were projects that were stopped multiple times. At the time the survey was done there were 3,682 projects running and 431, or 12%, of these were on time and on budget. One of the key results of The CHAOS Report is the suggested project success, challenged, and impaired factors. The three most important factors for each project class are quite similar with each other as can be seen in Table 1. Table 1 also shows that the requirements have an important role when the project outcome is considered. Table 1. Project success, challenged, and impaired factors (The Standish Group 1995). Success factors Challenged factors Impaired factors 1. User involvement 1. Lack of user input 1. Incomplete requirements 2. Executive management support 2. Incomplete requirements and specifications 2. Lack of user involvement 3. Clear statement of requirements 3. Changing requirements and specifications 3. Lack of resources Other studies of interest from the software project viewpoint include a software project risk identification framework and RE as a success factor for software projects. The risk identification framework study was done in 1998 and it identified 11 global software project risk factors six of which can be considered requirements related. The other study about RE as success factor for software projects identify ten best RE practices for software projects. These studies are presented in more detail in Section 2.1 (Software Projects and Requirements) in (Nikula 2002). 2.2 State of the Practice in Requirements Engineering The state of the practice in RE in industry is not very encouraging. It is estimated that over 76% of all enterprises have deficient RE practices (Jones 1996) and this result is supported by many studies on RE (see, e.g., (Kamsties et al. 1998; Nikula et al. 2000)). In this section a quick look is provided to state of the practice in RE and a more general perspective is provided from the software maturity point of view. There is no generally accepted assessment scheme for RE. The REAIMS project has suggested such a thing (Sommerville and Sawyer 1997) and it has been accepted fairly well by the academia. Unfortunately this scheme has not been applied much in practice and only very few studies have reported use of the REAIMS model in RE

108 Lappeenranta University of Technology Practical RE in Short 4(47) assessment. In one such survey (Nikula et al. 2000) a quick assessment was done based on the REAIMS top ten practices that should be applied by all companies. The result of this survey is shown in Figure 1: from the maximum of 30 points the best company got 28 points and two companies did not get any points. This result reflects quite well the overall feeling of the situation in these companies some companies have clearly invested in RE and it shows, but most companies have yet not established good RE practices. Point Gain Company Figure 1. REAIMS Top Ten -point gains for the companies. The maximum point gain was 30; the best result was 28 points and two companies did not get any points. Figure 2 shows the top ten practices and how the companies applied these practices in their work. The standard document structure is the most used practice in the surveyed companies, but even it is used in a standard manner in only four companies. 1. Standard doc structure 2. Use simple language 3. Formal insp. done 4. Easy change planned 5. Reqs have unique id 6. Reqs template used 7. Analysis checklist used 8. Conflict resol. planned 9. RM policies defined 10. Doc checklist defined Standard Normal Discret. Never Company count Figure 2. REAIMS Top Ten questions and ratings in Pareto order.

109 Lappeenranta University of Technology Practical RE in Short 5(47) These results support the general opinion about the RE practices in industry. In the lack of any longitudinal studies it is impossible to say whether the situation is changing somehow. However, the Software Engineering Institute introduced a Capability Maturity Model (CMM) in the late 80 s and they have also developed a database of the assessment results (Software Engineering Institute 2002). Studying the results of the assessments between 1987 and 2001 the general trend towards higher software engineering maturity levels can be seen (Figure 3). For example, the number of companies in the first or initial level has reduced to a half since starting to record the assessment results. Figure 3. Trends in CMM profile in March 2002 (Software Engineering Institute 2002). To summarize the state of the practice in industry it is not very promising. Practically all the studies on the subject have reported that the practices in industrial projects are in general very basic ones and that there is a general lack of knowledge both regarding RE techniques and methods, and their usage. Results from three such studies in addition to a more detailed account of this state of the practice survey can be found in (Nikula 2002). An encouraging observation is, though, that the general trend in software engineering is towards higher maturity levels as indicated by the Software Engineering Institute s reports.