SOFTWARE ENGINEERING PROJECT REPORT, Study Guides, Projects, Research of Software Project Management

Download SOFTWARE ENGINEERING PROJECT REPORT and more Study Guides, Projects, Research Software Project Management in PDF only on Docsity! 1 Software Engineering Project Report   A Sample Document for Generating Consistent Professional Reports Prepared by John T. Bell for use in CS 440 at the University of Illinois Chicago September 2013 2 How to Use This Document  This document is intended as a sample template that can be copied and edited to suit a particular software engineering project. It was assembled from a combination of documents [1], [2], and [3]. Styles This document was written in Microsoft Word, and makes heavy use of styles. The styles dialog is initially located on the menu bar under the “Home” tab in MS Word. It is recommended that the styles dialog be pulled off into a separate window when working on formatting of the document. If each paragraph is assigned a style, then modifying that particular style will affect all paragraphs in the document having the same style. The table of contents uses the document headings and sub-headings to automatically generate table of contents information. Tracking Changes and Multiple Authors The “Review” tab in MS Word contains several tools that are of particular use when editing large documents, particularly when multiple authors are involved: The “Tracking” section allows you to track the ( proposed ) changes to a document, and to step through each proposed change to either accept or reject the proposed changes. The “Compare” section allows you to merge changes proposed by different authors, ( which will be marked in separate colors for identification ), and then to use the change tracking tools described above to accept or deny each change. The recommended procedure is to start with each author having a copy of a base document, ( possibly this template. ) Then each author changes the section(s) they are responsible for, and submits their changed version to one person who acts as the overall document editor. This author merges the changes, selectively accepts or rejects each change, and then distributes a new base document to all authors for the next round of changes. It is also possible to merge the changes and then distribute the document, so that all authors can review the proposed changes. ( The latter approach may be appropriate for documents such as bylaws, in which the changes must be approved by a committee or a vote before they can be accepted. ) 5 7c  Data Dictionary for Any Included Models ............................................................. 30  8  Relevant Facts and Assumptions .................................................................................... 31  8a  Facts ........................................................................................................................ 31  8b  Assumptions ........................................................................................................ 31  II  Requirements .................................................................................................................. 33  9  Product Use Cases .......................................................................................................... 33  9a  Use Case Diagrams ................................................................................................. 33  9b  Product Use Case List ......................................................................................... 34  9c  Individual Product Use Cases ................................................................................. 35  10  Functional Requirements ................................................................................................ 35  11  Data Requirements ......................................................................................................... 36  12  Performance Requirements ............................................................................................ 38  12a  Speed and Latency Requirements ....................................................................... 38  12b  Precision or Accuracy Requirements .................................................................. 39  12c  Capacity Requirements ....................................................................................... 39  13  Dependability Requirements .......................................................................................... 40  13a  Reliability Requirements ..................................................................................... 40  13b  Availability Requirements ................................................................................... 40  13c  Robustness or Fault-Tolerance Requirements ..................................................... 41  13d  Safety-Critical Requirements .............................................................................. 42  14  Maintainability and Supportability Requirements .......................................................... 43  14a  Maintenance Requirements ................................................................................. 43  14b  Supportability Requirements ............................................................................... 43  14c  Adaptability Requirements .................................................................................. 44  14d  Scalability or Extensibility Requirements ........................................................... 44  14e  Longevity Requirements ..................................................................................... 45  15  Security Requirements .................................................................................................... 45  15a  Access Requirements .......................................................................................... 45  15b  Integrity Requirements ........................................................................................ 46  15c  Privacy Requirements ......................................................................................... 47  15d  Audit Requirements ............................................................................................. 48  15e  Immunity Requirements ...................................................................................... 48  16  Usability and Humanity Requirements .......................................................................... 48  16a  Ease of Use Requirements ................................................................................... 48  16b  Personalization and Internationalization Requirements ...................................... 50  16c  Learning Requirements ....................................................................................... 51  6 16d  Understandability and Politeness Requirements ................................................. 52  16e  Accessibility Requirements ................................................................................. 52  16f  User Documentation Requirements .................................................................... 53  16g  Training Requirements ........................................................................................ 54  17  Look and Feel Requirements .......................................................................................... 54  17a  Appearance Requirements ................................................................................... 54  17b  Style Requirements ............................................................................................. 55  18  Operational and Environmental Requirements .............................................................. 56  18a  Expected Physical Environment .......................................................................... 56  18b  Requirements for Interfacing with Adjacent Systems ......................................... 56  18c  Productization Requirements .............................................................................. 57  18d  Release Requirements ......................................................................................... 58  19  Cultural and Political Requirements ............................................................................... 58  19a  Cultural Requirements......................................................................................... 58  19b  Political Requirements ........................................................................................ 59  20  Legal Requirements ........................................................................................................ 60  20a  Compliance Requirements .................................................................................. 60  20b  Standards Requirements ...................................................................................... 61  III  Design ............................................................................................................................. 61  21  System Design ................................................................................................................ 61  21a  Design goals ........................................................................................................ 61  22  Current Software Architecture ....................................................................................... 63  23  Proposed Software Architecture ..................................................................................... 63  23a  Overview ............................................................................................................. 63  23b  Class Diagrams .................................................................................................... 63  23c  Dynamic Model ................................................................................................... 63  23d  Subsystem Decomposition .................................................................................. 63  23e  Hardware / software mapping ............................................................................. 64  23f  Data Dictionary ................................................................................................... 64  23g  Persistent Data management ............................................................................... 64  23h  Access control and security ................................................................................. 64  23i  Global software control ....................................................................................... 64  23j  Boundary conditions ........................................................................................... 65  24  Subsystem services ......................................................................................................... 65  25  User Interface ................................................................................................................. 65  7 26  Object Design ................................................................................................................. 65  26a  Object Design trade-offs ..................................................................................... 65  26b  Interface Documentation guidelines .................................................................... 65  26c  Packages .............................................................................................................. 66  26d  Class Interfaces ................................................................................................... 66  IV  Test Plans ........................................................................................................................ 66  27  Features to be tested / not to be tested ............................................................................ 66  28  Pass/Fail Criteria ............................................................................................................ 66  29  Approach ........................................................................................................................ 66  30  Suspension and resumption ............................................................................................ 67  31  Testing materials ( hardware / software requirements ) ................................................. 67  32  Test cases ........................................................................................................................ 67  33  Testing schedule ............................................................................................................. 67  V  Project Issues .................................................................................................................. 67  34  Open Issues ..................................................................................................................... 67  35  Off-the-Shelf Solutions .................................................................................................. 68  35a  Ready-Made Products ......................................................................................... 68  35b  Reusable Components ......................................................................................... 69  35c  Products That Can Be Copied ............................................................................. 69  36  New Problems ................................................................................................................ 69  36a  Effects on the Current Environment .................................................................... 69  36b  Effects on the Installed Systems.......................................................................... 70  36c  Potential User Problems ...................................................................................... 70  36d  Limitations in the Anticipated Implementation Environment That May Inhibit the New Product ............................................................................................................. 70  36e  Follow-Up Problems ........................................................................................... 71  37  Tasks ............................................................................................................................... 71  37a  Project Planning .................................................................................................. 71  37b  Planning of the Development Phases .................................................................. 72  38  Migration to the New Product ........................................................................................ 73  38a  Requirements for Migration to the New Product ................................................ 73  38b  Data That Has to Be Modified or Translated for the New System ..................... 73  10 List of Tables  If a document contains a large number of tables, then it is appropriate to include a list of tables at the beginning of the document, following the table of contents. Each table should include a title, and be numbered in a consistent logical fashion. The following list of tables was automatically generated from table captions ( see below), and can be automatically updated by right-clicking on the table below and selecting “Update Field”. This feature is located in the “Captions” section of the “References” tab in MS Word. Note: Remove this instructional paragraph. Table 1- Sample Table of Survey Dive Activity .......................................................................... 11  11 The following sample table and figure are only here to initialize the list of figures and list of tables above. They should be removed when real ones are included in the document. ( I.e. delete this entire page when you can. ) Date Participants Activities Notes Table 1- Sample Table of Survey Dive Activity Figure 1 - Sample Image of a Survey Dive Boat ( photo by Tony Kiefer ) 12 I Project Description  1 Project Overview  A brief description of the product to be produced, before getting into details. 2 The Purpose of the Project   2a The User Business or Background of the Project Effort  Content content, motivation, examples and Considerations A short description of the business being done, its context, and the situation that triggered the development effort. It should also describe the work that the user intends to do with the delivered product. Motivation Without this statement, the project lacks justification and direction. Considerations You should consider whether the user problem is serious, and whether and why it needs to be solved. 2b Goals of the Project  ( Note: This item and the following one together cover the " Objectives and success criteria of the project" item specified by Bruegge & DuToit. ) Content This boils down to one sentence, or at most a few sentences, that say why we want this product. Here is where you state the real reason the product is being developed. Motivation There is a danger that this purpose may get lost along the way. As the development effort heats up, and as the customer and developers discover more about what is possible, the system could potentially wander away from the original goals as it undergoes construction. This is a bad thing unless there is some deliberate act by the client to change the goals. It may be necessary to appoint a person to be custodian of the goals, but it is probably sufficient to make the goals public and periodically remind the developers of them. It should be mandatory to acknowledge the goals at every review session. Examples 15 Examples Considerations The names used on the context diagram should be consistent with the naming conventions and data dictionary definitions presented in section 5. Without these definitions, the context model lacks the required rigor, and it may be misunderstood. Relevant stakeholders must agree to the definitions of the interfaces shown on the context model. Weather Station Readings District Weather Forecasts Treated Road Truck Change Road De-icing Schedule New Weather Station Changed Weather Station Changed Road Amended De-icing Schedule Untreated Road Reminder Thermal Maps Truck Breakdown Failed Weather Station Alert Weather Sta tionThermal Mapping Supplier Road Engineering Truck Depot Weather Forecasting Service The work of predicting and scheduling the de-icing of r oads 16 3c Work Partitioning  Note: Volere talks of dividing up the work according to the different business events to which the business must respond. However each response to a business event is effectively a use-case, so Volere’s list of business events is effectively the same as a use-case diagram and a descriptive list of the associated use-cases. Content A list showing all business events to which the work responds. Business events are happenings in the real world that affect the work. They also happen because it is time for the work to do something—for example, produce weekly reports, remind nonpaying customers, check the status of a device, and so on. The response to each event is called a business use case; it represents a discrete partition of work that contributes to the total functionality of the work. The event list includes the following elements: ● Event name ● Input from adjacent systems (identical with name on context diagram) ● Output to adjacent systems (identical with name on context diagram) ● Brief summary of the business use case (This is optional, but we have found it is a very useful first step in defining the requirements for the business use case—you can think of it as a mini-scenario.) Motivation To identify logical chunks of the system that can be used as the basis for discovering detailed requirements. These business events also provide the subsystems that can be used as the basis for managing detailed analysis and design. 17 Example Business Event List Event Name Input and Output Summary 1. Weather Station transmits reading Weather Station Readings (in) Record the readings as belonging to the weather station. 2. Weather Service forecasts weather District Weather Forecast (in) Record the forecast. 3. Road engineers advise changed roads Changed Road (in) Record the new or changed road. Check that all appropriate weather stations are attached. 4. Road Engineering installs new Weather Station New Weather Station (in) Record the weather station and attach it to the appropriate roads. 5. Road Engineering changes Weather Station Changed Weather Station (in) Record the changes to the weather station. 6. Time to test Weather Stations Failed Weather Station Alert (out) Determine if any weather stations have not transmitted for two hours, and inform Road Engineering of any failures. 7. Truck Depot changes a truck Truck Change (in) Record the changes to the truck. 8. Time to detect icy roads Road De-icing Schedule (out) Predict the ice situation for the next two hours. Assign a truck to any roads that will freeze. Issue the schedule. 9. Truck treats a road Treated Road (in) Record the road as being in a safe condition for the next three hours. 10 Truck Depot reports problem with truck Truck Breakdown (in) Amended Gritting Schedule (out) Reassign available trucks to the previously assigned roads. 11. Time to monitor road treatment Untreated Road Reminder (out) Check that all scheduled roads have been treated in the assigned time, and issue reminders for any untreated roads. Considerations Attempting to list the business events is a way of testing the work context. This activity uncovers uncertainties and misunderstandings about the project and facilitates 20 5c Hands­On Users of the Product   Content A list of a special type of stakeholder—the potential users of the product. For each category of user, provide the following information: ● User name/category: Most likely the name of a user group, such as schoolchildren, road engineers, or project managers. ● User role: Summarizes the users’ responsibilities. ● Subject matter experience: Summarizes the users’ knowledge of the business. Rate as novice, journeyman, or master. ● Technological experience: Describes the users’ experience with relevant technology. Rate as novice, journeyman, or master. ● Other user characteristics: Describe any characteristics of the users that have an effect on the requirements and eventual design of the product. For example: Physical abilities/disabilities Intellectual abilities/disabilities Attitude toward job Attitude toward technology Education Linguistic skills Age group Gender Motivation Users are human beings who interface with the product in some way. Use the characteristics of the users to define the usability requirements for the product. Users are also known as actors. Examples Users can come from wide variety of (sometimes unexpected) sources. Consider the possibility of your users being clerical staff, shop workers, managers, highly trained operators, the general public, casual users, passers-by, illiterate people, tradesmen, students, test engineers, foreigners, children, lawyers, remote users, people using the system over the telephone or an Internet connection, emergency workers, and so on. 21 5d Priorities Assigned to Users  Content Attach a priority to each category of user. This gives the importance and precedence of the user. Prioritize the users as follows: ● Key users: They are critical to the continued success of the product. Give greater importance to requirements generated by this category of user. ● Secondary users: They will use the product, but their opinion of it has no effect on its long-term success. Where there is a conflict between secondary users’ requirements and those of key users, the key users take precedence. ● Unimportant users: This category of user is given the lowest priority. It includes infrequent, unauthorized, and unskilled users, as well as people who misuse the product. The percentage of the type of user is intended to assess the amount of consideration given to each category of user. Motivation If some users are considered to be more important to the product or to the organization, then this preference should be stated because it should affect the way that you design the product. For instance, you need to know if there is a large customer group who has specifically asked for the product, and for which, if they do not get what they want, the results could be a significant loss of business. Some users may be listed as having no impact on the product. These users will make use of the product, but have no vested interest in it. In other words, these users will not complain, nor will they contribute. Any special requirements from these users will have a lower design priority. 5e User Participation  Content Where appropriate, attach to the category of user a statement of the participation that you think will be necessary for those users to provide the requirements. Describe the contribution that you expect these users to provide—for example, business knowledge, interface prototyping, or usability requirements. If possible, assess the minimum amount of time that these users must spend for you to be able to determine the complete requirements. Motivation Many projects fail through lack of user participation, sometimes because the required degree of participation was not made clear. When people have to make a choice 22 between getting their everyday work done and working on a new project, the everyday work usually takes priority. This requirement makes it clear, from the outset, that specified user resources must be allocated to the project. 5f Maintenance Users and Service Technicians  Content Maintenance users are a special type of hands-on users who have requirements that are specific to maintaining and changing the product. Motivation Many of these requirements will be discovered by considering the various types of maintenance requirements detailed in section 14. However, if we define the characteristics of the people who maintain the product, it will help to trigger requirements that might otherwise be missed. 5g Other Stakeholders  Content The roles and (if possible) names of other people and organizations who are affected by the product, or whose input is needed to build the product. Examples of stakeholders: ● Sponsor ● Testers ● Business analysts ● Technology experts ● System designers ● Marketing experts ● Legal experts ● Domain experts ● Usability experts ● Representatives of external associations For a complete checklist, download the stakeholder analysis template at www.volere.co.uk. 25 Motivation To describe the technological environment into which the product must fit. The environment places design constraints on the product. This part of the specification provides enough information about the environment for the designers to make the product successfully interact with its surrounding technology. The operational requirements are derived from this description. Examples Examples can be shown as a diagram, with some kind of icon to represent each separate device or person (processor). Draw arrows to identify the interfaces between the processors, and annotate them with their form and content. Considerations All component parts of the current system, regardless of their type, should be included in the description of the implementation environment. If the product is to affect, or be important to, the current organization, then include an organization chart. 6c Partner or Collaborative Applications  Content This describes applications that are not part of the product but with which the product will collaborate. They can be external applications, commercial packages, or preexisting in-house applications. Motivation To provide information about design constraints caused by using partner applications. By describing or modeling these partner applications, you discover and highlight potential problems of integration. Examples This section can be completed by including written descriptions, models, or references to other specifications. The descriptions must include a full specification of all interfaces that have an effect on the product. Considerations Examine the work context model to determine whether any of the adjacent systems should be treated as partner applications. It might also be necessary to examine some of the details of the work to discover relevant partner applications. 26 6d Off­the­Shelf Software  Content This describes commercial, open source, or any other off-the-shelf software (OTS) that must be used to implement some of the requirements for the product. It could also apply to nonsoftware OTS components such as hardware or any other commercial product that is intended as part of the solution. Motivation To identify and describe existing commercial, free, open source, or other products to be incorporated into the eventual product. The characteristics, behavior, and interfaces of the package are design constraints. Examples This section can be completed by including written descriptions, models, or references to supplier’s specifications. Considerations When gathering requirements, you may discover requirements that conflict with the behavior and characteristics of the OTS software. Keep in mind that the use of OTS software was mandated before the full extent of the requirements became known. In light of your discoveries, you must consider whether the OTS product is a viable choice. If the use of the OTS software is not negotiable, then the conflicting requirements must be discarded. Note that your strategy for discovering requirements is affected by the decision to use OTS software. In this situation you investigate the work context in parallel with making comparisons with the capabilities of the OTS product. Depending on the comprehensibility of the OTS software, you might be able to discover the matches or mismatches without having to write each of the business requirements in atomic detail. The mismatches are the requirements that you will need to specify so that you can decide whether to satisfy them by either modifying the OTS software or modifying the business requirements. Given the spate of lawsuits in the software arena, you should consider whether any legal implications might arise from your use of OTS. You can cover this in the section on Legal Requirements. Note the subtle difference between this section and section 35 below. This section documents OTS solutions that must be included in the final solution, and the latter offers suggestions for OTS that could be included. 27 6e Anticipated Workplace Environment  Content This describes the workplace in which the users are to work and use the product. It should describe any features of the workplace that could have an effect on the design of the product, and the social and culture of the workplace. Motivation To identify characteristics of the workplace so that the product is designed to compensate for any difficulties. Examples The printer is a considerable distance from the user’s desk. This constraint suggests that printed output should be deemphasized. The workplace is noisy, so audible signals might not work. The workplace is outside, so the product must be weather resistant, have displays that are visible in sunlight, and allow for the effect of wind on any paper output. The product is to be used in a library; it must be extra quiet. The product is a photocopier to be used by an environmentally conscious organization; it must work with recycled paper. The user will be standing up or working in positions where he must hold the product. This suggests a hand-held product, but only a careful study of the users’ work and workplace will provide the necessary input to identifying the operational requirements. Considerations The physical work environment constrains the way that work is done. The product should overcome whatever difficulties exist; however, you might consider a redesign of the workplace as an alternative to having the product compensate for it. 6f Schedule Constraints   Content Any known deadlines, or windows of opportunity, should be stated here. Motivation To identify critical times and dates that have an effect on product requirements. If the deadline is short, then the requirements must be kept to whatever can be built within the time allowed. 30 From the beginning of the project, emphasize the need to avoid homonyms and synonyms. Explain how they increase the cost of the project. 7b UML and Other Notation Used in This Document  Content This section should describe the specific meaning of any symbols, punctuation, subscripts, superscripts, etc. used commonly throughout the document. If following published or common standards, then it is acceptable to reference those standards, and list any exceptions. Motivation If the distinction between a hollow arrow and a solid arrow is significant, for example, then everyone must know exactly what the distinctions and meanings are. Considerations If a particular notation is only used in one place, say on a single diagram or in a single section, then it may be more appropriate to document it in that specific location. Example This document generally follows the Version 2.0 OMG UML standard, as described by Fowler in [4]. Any exceptions are noted where used. 7c Data Dictionary for Any Included Models  Content Dictionary definitions of all information flows and stores used in models. Particular consideration should be given to defining the data attributes of all flows shown the context models (see sections 7 and 8). This section should also contain any technical specifications for interfaces shown on the context models. Motivation The context diagram provides an accurate definition of the scope of the work being studied or the scope of the product to be built. This definition can be completely accurate only if the information flows bordering the scope have their attributes defined. Examples Road de-icing schedule = issue number + {road section identifier + treatment start time + critical start time + truck identifier} + depot identifier 31 As you progress through the requirements specification, define each of the elementary terms in detail. Considerations The dictionary provides a link between the requirements analysts and the implementers. The implementers add implementation details to the terms in the dictionary, defining how the data will be implemented. Also, implementers add terms that are present because of the chosen technology and that are independent of the business requirements. 8 Relevant Facts and Assumptions  8a Facts  Content Factors that have an effect on the product, but are not mandated requirements constraints. They could be business rules, organizational systems, or any other activities that have an effect on this product. Facts are things you want the reader of the specification to know. Motivation Relevant facts provide background information to the specification readers, and might contribute to requirements. They will have an effect on the eventual design of the product. Examples One ton of de-icing material will treat three miles of single-lane roadway. The existing application is 10,000 lines of C code. 8b Assumptions  Content A list of the assumptions that the developers are making. These assumptions might be about the intended operational environment, but can be about anything that has an effect on the product. As part of managing expectations, assumptions also contain statements about what the product will not do. Motivation To make people declare the assumptions that they are making. Also, to make everyone on the project aware of assumptions that have already been made. 32 Examples Assumptions about new laws or political decisions. Assumptions about what your developers expect to be ready in time for them to use— for example, other parts of your products, the completion of other projects, software tools, or software components. Assumptions about the technological environment in which the product will operate. These assumptions should highlight areas of expected compatibility. The software components that will be available to the developers. Other products being developed at the same time as this one. The availability and capability of bought-in components. Dependencies on computer systems or people external to this project The requirements that will specifically not be carried out by the product. Considerations We often make unconscious assumptions. It is necessary to talk to the members of the project team to discover any unconscious assumptions that they have made. Ask stakeholders (both technical and business-related) questions such as these: ● What software tools are you expecting to be available? ● Will there be any new software products? ● Are you expecting to use a current product in a new way? ● Are there any business changes you are assuming we will be able to deal with? It is important to state these assumptions up front. You might also consider the probability of whether the assumption is correct and, where relevant, a list of alternatives if something that is assumed does not happen. The assumptions are intended to be transient. That is, they should all be cleared by the time the specification is released—the assumption should have become either a requirement or a constraint. For example, if the assumption related to the capability of a product that is intended to be a partner product to yours, then the capability should have been proven satisfactory, and it becomes a constraint to use it. Conversely, if the bought-in product is not suitable, then it becomes a requirement for the project team to construct the needed capability. 35 9c Individual Product Use Cases  Use cases are similar to scenarios, in that both tell the story of how the system interacts with the user(s) in response to some business event or while conducting some business task. The difference is that use-cases are much more formal, with certain pre-determined sections for each use-case, and that use-cases indicate clearly what action the system takes in response to what actions taken by the user. For example, here is Figure 4.7 from "Object Oriented Software Engineering" by Bruegge and DuToit: 10 Functional Requirements  Content A specification for each functional requirement. As with all types of requirements, use the requirements shell. A full explanation is included in this template’s introductory material. 36 Motivation To specify the detailed functional requirements for the activity of the product. Examples Fit Criterion Each functional requirement should have a fit criterion or a test case. In any event, the fit criterion is the benchmark to allow the tester to determine whether the implemented product has met the requirement. Considerations If you have produced an event/use case list (see sections 7b and 8a), then you can use it to help you trigger the functional requirements for each event/use case. If you have not produced an event/use case list, give each functional requirement a unique number and, to help with traceability, partition these requirements into event/use case–related groups later in the development process. 11 Data Requirements   Content A specification of the essential subject matter, business objects, entities, and classes that are germane to the product. It might take the form of a first-cut class model, an 9 The product s hall re cord a ll t he roads t hat h ave been t reated To be able to schedule unt reated roads and highlight pot ent ial danger Arnold Snow - Chief Engineer The recorded t reat ed and unt reated roads shall agree wit h t he drivers’road t reat ment logs. Creat ed Februar y 29,2006 75 7, 9 3 5 Description: Rationale: Originator: Fit Criterion: Customer S atisfaction: Priority: Suppor ting Materials: History: Copyright © Atlantic Systems Guild Requirement #: Event/use case #: Customer Dissatisfaction: Conflicts: Volere Requirement Type: 37 object model, or a domain model. Alternatively, these requirements might be described by defining the terms in the dictionary described in section 5. Motivation To clarify the system’s subject matter, thereby triggering recognition of requirements not yet considered. Example This is a model of the system’s business subject matter using the Unified Modeling Language (UML) class model notation. You can use any type of data or object model to capture this knowledge. The issue is to capture the meaning of the business subject matter and the connections between the individual parts, and to show that you are consistent within your project. If you have an established company standard notation, use that, as it will help you to reuse knowledge between projects. Considerations Are there any data or object models for similar or overlapping systems that might be a useful starting point? Is there a domain model for the subject matter dealt with by this system? District Forecast Road Road Section Weather Sta tion Temperatur e Reading Depot Truck S S S1 1 S 1 S1 S 1S S SSS 40 Fit Criterion In this case, the requirement description is quantified, and thus can be tested. 13 Dependability Requirements  13a Reliability Requirements  Content This section quantifies the necessary reliability of the product. The reliability is usually expressed as the allowable time between failures, or the total allowable failure rate. Motivation It is critical for some products not to fail too often. This section allows you to explore the possibility of failure and to specify realistic levels of service. It also gives you the opportunity to set the client’s and users’ expectations about the expected frequency and significance of potential failures. Examples The product shall not fail more than once per day. No data shall be lost or damaged in the event of a failure. ( This is an example of a fail-safe requirement, which states that the product is allowed to fail, but it must do so safely. ) Considerations Consider carefully whether the real requirement for your product is that it is available for use or that it does not fail at any time. Consider also the cost of reliability and availability, and whether it is justified for your product. 13b Availability Requirements  Content This section quantifies the necessary availability of the product. The availability is usually expressed as the fraction of total time that the system is up and available for use. Availability is a function of the mean time between failures, the mean time required to bring the system back up after a failure, and the mean time the system is expected to be down for routine maintenance. 41 Motivation There is a subtle distinction between how often a system goes down ( reliability )3and how much total time it spends being down ( availability ). This section allows you to specify realistic expectations about the amount of time that the product will be available for use. Examples The product shall be available for use 24 hours per day, 365 days per year. The product shall be available for use between the hours of 8:00 A.M. and 5:30 P.M. The escalator shall run from 6 A.M. until 10 P.M. or the last flight arrives. The product shall achieve 99 percent uptime. Considerations Consider carefully whether the real requirement for your product is that it is available for use or that it does not fail at any time. Consider also the cost of reliability and availability, and whether it is justified for your product. The sections on reliability and availability can sometimes be combined. 13c Robustness or Fault­Tolerance Requirements  Content Robustness specifies the ability of the product to continue to function under abnormal circumstances. Motivation To ensure that the product is able to provide some or all of its services after or during some abnormal happening in its environment. Examples The product shall continue to operate in local mode whenever it loses its link to the central server. The product shall provide 10 minutes of emergency operation should it become disconnected from the electricity source. 42 Considerations Abnormal happenings can almost be considered normal. Today’s products are so large and complex that there is a good chance that at any given time, one component will not be functioning correctly. Robustness requirements are intended to prevent total failure of the product. You could also consider disaster recovery in this section. This plan describes the ability of the product to reestablish acceptable performance after faults or abnormal happenings. 13d Safety­Critical Requirements  Content Quantification of the perceived risk of damage to people, property, and environment. Different countries have different standards, so the fit criteria must specify precisely which standards the product must meet. Motivation To understand and highlight the damage that could potentially occur when using the product within the expected operational environment. Examples The product shall not emit noxious gases that damage people’s health. The heat exchanger shall be shielded from human contact. Fit Criterion The product shall be certified to comply with the Health Department’s standard E110- 98. It is to be certified by qualified testing engineers. No member of a test panel of [specified size] shall be able to touch the heat exchanger. The heat exchanger must also comply with safety standard [specify which one]. Considerations The example requirements given here apply to some, but not all, products. It is not possible to give examples of every variation of safety-critical requirement. To make the template work in your environment, you should customize it by adding examples that are specific to your products. Also, be aware that different countries have different safety standards and laws relating to safety. If you plan to sell your product internationally, you must be aware 45 Motivation To ensure that the designers allow for future capacities. Examples The product shall be capable of processing the existing 100,000 customers. This number is expected to grow to 500,000 customers within three years. The product shall be able to process 50,000 transactions per hour within two years of its launch. 14e Longevity Requirements  Content This specifies the expected lifetime of the product. Motivation To ensure that the product is built based on an understanding of expected return on investment. Examples The product shall be expected to operate within the maximum maintenance budget for a minimum of five years. 15 Security Requirements  15a Access Requirements  Content Specification of who has authorized access to the product (both functionality and data), under what circumstances that access is granted, and to which parts of the product access is allowed. Motivation To understand the expectations for confidentiality aspects of the system. Examples Only direct managers can see the personnel records of their staff. Only holders of current security clearance can enter the building. 46 Fit Criterion System function name or system data name. User roles and/or names of people who have clearance. Considerations Is there any data that management considers to be sensitive? Is there any data that low-level users do not want management to have access to? Are there any processes that might cause damage or might be used for personal gain? Are there any people who should not have access to the system? Avoid stating how you will design a solution to the security requirements. For instance, don’t “design a password system.” Your aim here is to identify the security requirement; the design will then come from this description. Consider asking for help. Computer security is a highly specialized field, and one where improperly qualified people have no business. If your product has need of more than average security, we advise you to make use of a security consultant. Such consultants are not cheap, but the results of inadequate security can be even more expensive. 15b Integrity Requirements  Content Specification of the required integrity of databases and other files, and of the product itself. Motivation To understand the expectations for the integrity of the product’s data. To specify what the product will do to ensure its integrity in the case of an unwanted happening such as attack from the outside or unintentional misuse by an authorized user. Examples The product shall prevent incorrect data from being introduced. The product shall protect itself from intentional abuse. Considerations Organizations are relying more and more on their stored data. If this data should be come corrupt or incorrect—or disappear—then it could be a fatal blow to the organization. For example, almost half of small businesses go bankrupt after a fire destroys their computer systems. Integrity requirements are aimed at preventing complete loss, as well as corruption, of data and processes. 47 15c Privacy Requirements  Content Specification of what the product has to do to ensure the privacy of individuals about whom it stores information. The product must also ensure that all laws related to privacy of an individual’s data are observed. Motivation To ensure that the product complies with the law, and to protect the individual privacy of your customers. Few people today look kindly on organizations that do not observe their privacy. Examples The product shall make its users aware of its information practices before collecting data from them. The product shall notify customers of changes to its information policy. The product shall reveal private information only in compliance with the organization’s information policy. The product shall protect private information in accordance with the relevant privacy laws and the organization’s information policy. Considerations Privacy issues may well have legal implications, and you are advised to consult with your organization’s legal department about the requirements to be written in this section. Consider what notices you must issue to your customers before collecting their personal information. A notice might go so far as to warn customers that you intend to put a cookie in their computer. Also, do you have to do anything to keep customers aware that you hold their personal information? Customers must always be in a position to give or withhold consent when their private data is collected or stored. Similarly, customers should be able to view any private data and, where appropriate, ask for correction of the data. Also consider the integrity and security of private data—for example, when you are storing credit card information. 50 Considerations Refer to section 3, Users of the Product, to ensure that you have considered the usability requirements from the perspective of all the different types of users. It may be necessary to have special consulting sessions with your users and your client to determine whether any special usability considerations must be built into the product. You could also consider consulting a usability laboratory experienced in testing the usability of products that have a project situation (sections 1–7 of this template) similar to yours. 16b Personalization and Internationalization Requirements  Content This section describes the way in which the product can be altered or configured to take into account the user’s personal preferences or choice of language. The personalization requirements should cover issues such as the following: ● Languages, spelling preferences, and language idioms ● Currencies, including the symbols and decimal conventions ● Personal configuration options Motivation To ensure that the product’s users do not have to struggle with, or meekly accept, the builder’s cultural conventions. Examples The product shall retain the buyer’s buying preferences. The product shall allow the user to select a chosen language. Considerations Consider the country and culture of the potential customers and users of your product. Any out-of-country users will welcome the opportunity to convert to their home spelling and expressions. By allowing users to customize the way in which they use the product, you give them the opportunity to participate more closely with your organization as well as enjoy their own personal user experience. 51 You might also consider the configurability of the product. Configurability allows different users to have different functional variations of the product. 16c Learning Requirements   Content Requirements specifying how easy it should be to learn to use the product. This learning curve ranges from zero time for products intended for placement in the public domain (e.g., a parking meter or a web site) to a considerable amount of time for complex, highly technical products. (We know of one product where it was necessary for graduate engineers to spend 18 months in a training program before being qualified to use the product.) Motivation To quantify the amount of time that your client feels is allowable before a user can successfully use the product. This requirement guides designers to understand how users will learn the product. For example, designers may build elaborate interactive help facilities into the product, or the product may be packaged with a tutorial. Alternatively, the product may have to be constructed so that all of its functionality is apparent upon first encountering it. Examples The product shall be easy for an engineer to learn. A clerk shall be able to be productive within a short time. The product shall be able to be used by members of the public who will receive no training before using it. The product shall be used by engineers who will attend five weeks of training before using the product. Fit Criterion An engineer shall produce a [specified result] within [specified time] of beginning to use the product, without needing to use the manual. After receiving [number of hours] training a clerk shall be able to produce [quantity of specified outputs] per [unit of time]. [Agreed percentage] of a test panel shall successfully complete [specified task] within [specified time limit]. The engineers shall achieve [agreed percentage] pass rate from the final examination of the training. 52 Considerations Refer to section 3, Users of the Product, to ensure that you have considered the ease of learning requirements from the perspective of all the different types of users. 16d Understandability and Politeness Requirements  This section is concerned with discovering requirements related to concepts and metaphors that are familiar to the intended end users. Content This specifies the requirement for the product to be understood by its users. While “usability” refers to ease of use, efficiency, and similar characteristics, “understandability” determines whether the users instinctively know what the product will do for them and how it fits into their view of the world. You can think of understandability as the product being polite to its users and not expecting them to know or learn things that have nothing to do with their business problem. Motivation To avoid forcing users to learn terms and concepts that are part of the product’s internal construction and are not relevant to the users’ world. To make the product more comprehensible and thus more likely to be adopted by its intended users. Examples The product shall use symbols and words that are naturally understandable by the user community. The product shall hide the details of its construction from the user. Considerations Refer to section 3, Users of the Product, and consider the world from the point of view of each of the different types of users. 16e Accessibility Requirements  Content The requirements for how easy it should be for people with common disabilities to access the product. These disabilities might be related to physical disability or visual, hearing, cognitive, or other abilities. Motivation In many countries it is required that some products be made available to the disabled. In any event, it is self-defeating to exclude this sizable community of potential customers. 55 Considerations Even if you are using prototypes, it is important to understand the requirements for the appearance. The prototype is used to help elicit requirements; it should not be thought of as a substitute for the requirements. 17b Style Requirements   Content Requirements that specify the mood, style, or feeling of the product, which influences the way a potential customer will see the product. Also, the stakeholders’ intentions for the amount of interaction the user is to have with the product. In this section, you would also describe the appearance of the package if this is to be a manufactured product. The package may have some requirements as to its size, style, and consistency with other packages put out by your organization. Keep in mind the European laws on packaging, which require that the package not be significantly larger than the product it encloses. The style requirements that you record here will guide the designers to create a product as envisioned by your client. Motivation Given the state of today’s market and people’s expectations, we cannot afford to build products that have the wrong style. Once the functional requirements are satisfied, it is often the appearance and style of products that determine whether they are successful. Your task in this section is to determine precisely how the product shall appear to its intended consumer. Example The product shall appear authoritative. Fit Criterion After their first encounter with the product, 70 percent of representative potential customers shall agree they feel they can trust the product. Considerations The look and feel requirements specify your client’s vision of the product’s appearance. The requirements may at first seem to be rather vague (e.g., “conservative and professional appearance”), but these will be quantified by their fit criteria. The fit criteria give you the opportunity to extract from your client precisely what is meant, and give the designer precise instructions on what he is to accomplish. 56 18 Operational and Environmental Requirements  18a Expected Physical Environment  Content This section specifies the physical environment in which the product will operate. Motivation To highlight conditions that might need special requirements, preparations, or training. These requirements ensure that the product is fit to be used in its intended environment. Examples The product shall be used by a worker, standing up, outside in cold, rainy conditions. The product shall be used in noisy conditions with a lot of dust. The product shall be able to fit in a pocket or purse. The product shall be usable in dim light. The product shall not be louder than the existing noise level in the environment. Considerations The work environment: Is the product to operate in some unusual environment? Does this lead to special requirements? Also see section 11, Usability and Humanity Requirements. 18b Requirements for Interfacing with Adjacent Systems  Content This section describes the requirements to interface with partner applications and/or devices that the product needs to successfully operate. Motivation Requirements for the interfaces to other applications often remain undiscovered until implementation time. Avoid a high degree of rework by discovering these requirements early. Examples The products shall work on the last four releases of the five most popular browsers. 57 The new version of the spreadsheet must be able to access data from the previous two versions. Our product must interface with the applications that run on the remote weather stations. Fit Criterion For each inter-application interface, specify the following elements: ● The data content ● The physical material content ● The medium that carries the interface ● The frequency ● The volume 18c Productization Requirements  Content Any requirements that are necessary to make the product into a distributable or salable item. It is also appropriate to describe here the operations needed to install a software product successfully. Motivation To ensure that if work must be done to get the product out the door, then that work becomes part of the requirements. Also, to quantify the client’s and users’ expectations about the amount of time, money, and resources they will need to allocate to install the product. Examples The product shall be distributed as a ZIP file. The product shall be able to be installed by an untrained user without recourse to separately printed instructions. The product shall be of a size such that it can fit on one CD. Considerations Some products have special needs to turn them into a salable or usable product. You might consider that the product has to be protected such that only paid-up customers can access it. 60 The political requirements might be purely concerned with the politics inside your organization. However, in other situations you may need to consider the politics inside your customers’ organizations or the national politics of the country. 20 Legal Requirements  20a Compliance Requirements  Content A statement specifying the legal requirements for this system. Motivation To comply with the law so as to avoid later delays, lawsuits, and legal fees. Examples Personal information shall be implemented so as to comply with the Data Protection Act. Fit Criterion Lawyers’ opinion that the product does not break any laws. Considerations Consider consulting lawyers to help identify the legal requirements. Are there any copyrights or other intellectual property that must be protected? Conversely, do any competitors have copyrights on which you might be in danger of infringing? Is it a requirement that developers have not seen competitors’ code or even have worked for competitors? The Sarbanes-Oxley (SOX) Act, the Health Insurance Portability and Accountability Act (HIPAA) and the Gramm-Leach-Bliley Act may have implications for you. Check with your company lawyer. Might any pending legislation affect the development of this system? Are there any aspects of criminal law you should consider? Have you considered the tax laws that affect your product? Are there any labor laws (e.g., working hours) relevant to your product? 61 20b Standards Requirements  Content A statement specifying applicable standards and referencing detailed standards descriptions. This does not refer to the law of the land—think of it as an internal law imposed by your company. Motivation To comply with standards so as to avoid later delays. Example The product shall comply with MilSpec standards. The product shall comply with insurance industry standards. The product shall be developed according to SSADM standard development steps. Fit Criterion The appropriate standard-keeper certifies that the standard has been adhered to. Considerations It is not always apparent that there are applicable standards because their existence is often taken for granted. Consider the following: ● Do any industry bodies have applicable standards? ● Does the industry have a code of practice, watchdog, or ombudsman? ● Are there any special development steps for this type of product? III Design  21 System Design  21a Design goals  Content Design goals are important properties of the system to be optimized, and which may affect the overall design of the system. For example computer games place a higher priority on speed than accuracy, and so the physics engine for a computer game may make some rough approximations and assumptions that allow it to run as fast as possible while sacrificing accuracy, whereas the physics calculations performed by NASA must be much more rigorously correct, even at the expense of speed. 62 Note an important difference between design goals and requirements: Requirements include specific values that must be met in order for the product to be acceptable to the client, whereas design goals are properties that the designers strive to make "as good as possible", without specific criteria for acceptability. ( Note also that the same property may appear in both a requirement and a design goal, so a design goal may be to make the system run as fast as possible, with a requirement that says any speed below a certain specified threshold is unacceptable. ) 65 Considerations Example 23j Boundary conditions  Content Motivation Considerations Example 24 Subsystem services  Content Motivation Considerations Example 25 User Interface  Content Motivation Considerations Example 26 Object Design  26a Object Design trade­offs  Content Motivation Considerations Example 26b Interface Documentation guidelines  Content Motivation 66 Considerations Example 26c Packages  Content Motivation Considerations Example 26d Class Interfaces  Content Motivation Considerations Example IV Test Plans  27 Features to be tested / not to be tested  Content Motivation Considerations Example 28 Pass/Fail Criteria  Content Motivation Considerations Example 29 Approach  Content 67 Motivation Considerations Example 30 Suspension and resumption  Content Motivation Considerations Example 31 Testing materials ( hardware / software requirements )   Content Motivation Considerations Example 32 Test cases  Content Motivation Considerations Example 33 Testing schedule  Content Motivation Considerations Example V Project Issues  34 Open Issues   70 Motivation The intention is to discover early any potential conflicts that might otherwise not be realized until implementation time. Examples Any change to the scheduling system will affect the work of the engineers in the divisions and the truck drivers. Considerations Is it possible that the new system might damage some existing system? Can people be displaced or otherwise affected by the new system? These issues require a study of the current environment. A model highlighting the effects of the change is a good way to make this information widely understandable. 36b Effects on the Installed Systems   Content Specification of the interfaces between new and existing systems. Motivation Very rarely is a new development intended to stand completely alone. Usually the new system must coexist with some older system. This question forces you to look carefully at the existing system, examining it for potential conflicts with the new development. 36c Potential User Problems  Content Details of any adverse reaction that might be suffered by existing users. Motivation Sometimes existing users are using a product in such a way that they will suffer ill effects from the new system or feature. Identify any likely adverse user reactions, and determine whether we care about those reactions and what precautions we will take. 36d Limitations  in  the Anticipated  Implementation Environment That May  Inhibit the New Product  Content Statement of any potential problems with the new automated technology or new ways of structuring the organization. 71 Motivation The intention is to make early discovery of any potential conflicts that might otherwise not be realized until implementation time. Examples The planned new server is not powerful enough to cope with our projected growth pattern. The size and weight of the new product do not fit into the physical environment. The power capabilities will not satisfy the new product’s projected consumption. Considerations This requires a study of the intended implementation environment. 36e Follow­Up Problems   Content Identification of situations that we might not be able to cope with. Motivation To guard against situations where the product might fail. Considerations Will we create a demand for our product that we are not able to service? Will the new system cause us to run afoul of laws that do not currently apply? Will the existing hardware cope? There are potentially hundreds of unwanted effects. It pays to answer this question very carefully. 37 Tasks  37a Project Planning  Content Details of the life cycle and approach that will be used to deliver the product. A high- level process diagram showing the tasks and the interfaces between them is a good way to communicate this information. 72 Motivation To specify the approach that will be taken to deliver the product so that everyone has the same expectations. Considerations Depending on the maturity level of your process, the new product will be developed using your standard approach. However, some circumstances are unique to a particular product and will necessitate changes to your life cycle. While these considerations are not product requirements, they are needed if the product is to be successfully developed. If possible, attach an estimate of the time and resources needed for each task based on the requirements that you have specified. Attach your estimates to the events, use cases, and/or functions that you specified in sections 8 and 9. Do not forget issues related to data conversion, user training, and cutover. These needs are usually ignored when projects set implementation dates. 37b Planning of the Development Phases  Content Specification of each phase of development and the components in the operating environment. Motivation To identify the phases necessary to implement the operating environment for the new system so that the implementation can be managed. Fit Criterion Name of the phase. Required operational date. Operating environment components included. Functional requirements included. Nonfunctional requirements included. Considerations Identify which hardware and other devices are necessary for each phase of the new system. This list may not be known at the time of the requirements process, as these devices may be decided at design time. 75 It is also useful input to project management if you include the impact on the schedule, or the cost, if the risk does become a problem. 40 Costs  For details on how to estimate requirements effort and costs, refer to Appendix C Function Point Counting: A Simplified Introduction The other cost of requirements is the amount of money or effort that you have to spend building them into a product. Once the requirements specification is complete, you can use one of the estimating methods to assess the cost, expressing the result as a monetary amount or time to build. There is no best method to use when estimating. Keep in mind, however, that your estimates should be based on some tangible, countable artifact. If you are using this template, then, as a result of doing the work of requirements specification, you are producing many measurable deliverables. For example: ● Number of input and output flows on the work context ● Number of business events ● Number of product use cases ● Number of functional requirements ● Number of nonfunctional requirements ● Number of requirements constraints ● Number of function points The more detailed the work you do on your requirements, the more accurate your deliverables will be. Your cost estimate is the amount of resources you estimate each type of deliverable will take to produce within your environment. You can create some very early cost estimates based on the work context. At that stage, your knowledge of the work will be general, and you should reflect this vagueness by making the cost estimate a range rather than a single figure. As you increase your knowledge of the requirements, we suggest you try using function point counting—not because it is an inherently superior method, but because it is so widely accepted. So much is known about function point counting that it is possible to make easy comparisons with other products and other installations’ productivity. It is important that your client be told at this stage what the product is likely to cost. You usually express this amount as the total cost to complete the product, but you may also find it advantageous to point out the cost of the requirements effort, or the costs of individual requirements. 76 Whatever you do, do not leave the costs in the lap of hysterical optimism. Make sure that this section includes meaningful numbers based on tangible deliverables. 41 Waiting Room  Requirements that will not be part of the next release. These requirements might be included in future releases of the product. Content Any type of requirement. Motivation To allow requirements to be gathered, even though they cannot be part of the current development. To ensure that good ideas are not lost. Considerations The requirements-gathering process often throws up requirements that are beyond the sophistication of, or time allowed for, the current release of the product. This section holds these requirements in waiting. The intention is to avoid stifling the creativity of your users and clients, by using a repository to retain future requirements. You are also managing expectations by making it clear that you take these requirements seriously, although they will not be part of the agreed-upon product. Many people use the waiting room as a way of planning future versions of the product. Each requirement in the waiting room is tagged with its intended version number. As a requirement progresses closer to implementation, then you can spend more time on it and add details such as the cost and benefit attached to that requirement. You might also prioritize the contents of your waiting room. “Low-hanging fruit”— requirements that provide a high benefit at a low cost of implementation—are the highest-ranking candidates for the next release. You would also give a high waiting room rank to requirements for which there is a pent-up demand. 42 Ideas for Solutions  When you gather requirements, you focus on finding out what the real requirements are and try to avoid coming up with solutions. However, when creative people start to think about a problem, they always generate ideas about potential solutions. This section of the template is a place to put those ideas so that you do not forget them and so that you can separate them from the real business requirements. Content Any idea for a solution that you think is worth keeping for future consideration. This can take the form of rough notes, sketches, pointers to other documents, pointers to 77 people, pointers to existing products, and so on. The aim is to capture, with the least amount of effort, an idea that you can return to later. Motivation To make sure that good ideas are not lost. To help you separate requirements from solutions. Considerations While you are gathering requirements, you will inevitably have solution ideas; this section offers a way to capture them. Bear in mind that this section will not necessarily be included in every document that you publish. 43 Project Retrospective  Content At the end of every project you should reflect upon what methods were used that worked out well and should be repeated in the future, and also what methods did not work out well and should be avoided. Any recommendations, suggestions, or ideas for how to do things better in the future should also be documented Motivation To learn from experience, and to continually strive for process improvement. Considerations When things don't go well, it is important to distinguish whether the methods themselves were poor, or simply poorly implemented in this particular case, or whether they just weren't right for this particular project / group of engineers. VI Glossary  The glossary defines terms that may not be familiar to all readers. This is especially important if the document is expected to reach a wide and varied audience, such as school children. The glossary may be placed at either the beginning or the end of the document. Flotsam: Any part of a ship or its cargo found floating on the water, whether it was deliberately or accidentally lost by its original owners. Jetsam: Any part of a ship or its cargo that is deliberately cast off ( jettisoned ) by its original owners, generally in order to lighten the ship, whether it floats or sinks.