Agency Project Management Office. Guidance for Using the Requirements Document Template

Transcription

1 Agency Project Management Office Guidance for Using the Requirements Document Template Requirements Document Template Guidance

2 Introduction to this Document This document is designed to aid someone who needs to capture requirements for a project but is not necessarily formally trained or highly experienced in business analysis. It is designed to supplement the guidance in the Requirements Document Template. The Requirements Document describes the requirements that are derived from high level business goals, needs, and objectives for the project or product. The documented requirements are an expansion of these high level business needs into more detail. Requirements gathering and elicitation is a very important part of the process and is initiated prior to documenting the requirements. Project stakeholders and subject matter experts (SMEs) provide input to the requirements elicitation process (additional information regarding requirements elicitation can be found in the Requirements Management Process document). Various means of requirements gathering include: Brainstorming Document Analysis (review existing documentation) Focus Groups Interviews Observation Prototyping (storyboarding, screen flows, mock ups) Surveys Requirements Workshops The gathered requirements then need to be documented so they can be shared with and communicated to the project team for review and agreement. The finalized requirements should be made available for use in the design of the process or application, to create test cases for validation of the business goals, for input into user and administrator documentation, and for reference purposes by others as appropriate within the organization. Page 2 of 24

3 Some general notes on creating and working with the Requirements Document: After each update of the document make sure to manually update the revision number and date on: o the document header o in the Revision History and to describe the changes A note on language: examples in the document and template use will in requirements statements. This is a preference that can be agreed upon by the project or can be up to the author; shall or will are both acceptable. For nonnegotiable items the term must is used. For optional items, the term may is used. With regards to the last two terms, it is advisable to explain this usage in Section 1.5, Document Conventions. WordArt is used for the watermark in the Requirements Document Template; this is personal preference. When the document is approved and the Revision is just the number (Rev 01 with the letter dropped) then the Watermark should be changed to Approved. NOTE: The watermark when using WordArt is part of the document footer. The text (including footnotes) in the Requirements Document Template that is in blue and italic is for guidance only and should be deleted before the document is distributed for review. Sections 1 9 below explain the content of the Requirements Document in detail and the approaches to completing the individual sections of the document. In many instances, questions are posed to help the author think about and compile the relevant statements. Keep in mind when completing a Requirements Document that you may document as much or as little as is necessary for your project. Not all sections may be required; in this case, keep the section heading, note N/A under it and include, if necessary, a brief explanation as to why the section is not documented. Page 3 of 24

4 Table of Contents 1 Requirements Document Section 1: Introduction Requirements Document Section 2: Glossary Requirements Document Section 3: Referenced Documents Requirements Document Section 4: As-Is State Requirements Document Section 5: To-Be State Requirements Document Section 6: Business and Functional Requirements Requirements Document Section 7: Nonfunctional Requirements Requirements Document Section 8: Requirements Traceability Matrix Requirements Document Section 9: Appendix Graphical Tools Requirements Workflow Glossary Index Page 4 of 24

5 1 Requirements Document Section 1: Introduction Background/Executive Summary This section describes the project and its goals. Explain the business need/problem; what are the existing inefficiencies, desired improvements, etc. that are driving this project? What is the proposed solution and approach to solving the business need or problem? Why is this project important, what will it accomplish? What is the justification for the proposed solution? Reference relevant project documents such as the Scope Statement, Business Case, Project Charter, etc. if applicable. Project Scope Describe the scope of the project; what will it accomplish? Will it encompass breaking the work into smaller, multiple projects due to time constraints and/or requirements prioritization? If the project applies to an information system or application, will there be one or more modules or components? Also, describe what the project will not deliver; what is out of scope. Stakeholders List the stakeholders for the project and the contributors to the requirements in the document and their roles. A stakeholder is an individual or group that has a vested interest, directly or indirectly, in the project or a decision or proposed action that affects the project. Document Scope List or describe what the document will cover and what the document will not cover. Consider the project scope and explain what you are covering in this document; state if it is a subset of the project or not. Document Conventions Describe any writing standards (symbols, text) or typographical conventions that are used in this document such as fonts or highlighting that has special significance (other than the built-in headings and styles). Describe any naming conventions or use of terms throughout the document that are not captured in the glossary. Page 5 of 24

6 Assumption: Factor or condition which is considered to be true without proof. Assumptions and Dependencies List any assumptions applicable to the project as a whole or to its specific parts. An example of an assumption is: The tool will not be rolled out to the counties yet, so they will not need training or support during Phase 1. Dependency: Factor or condition which must be present to allow project completion. List dependencies that the system or project has on outside entities, other projects, other systems, other requirements, etc. and vice versa. Constraint: Boundary or limitation affecting the execution of the project. Constraints List any constraints on the system. Examples of system constraints include mandated software languages, software process requirements, prescribed use of developmental tools, architectural and design constraints, purchased components, etc. Other constraints may include legal requirements, technical standards, project schedule, budget, etc. 2 Requirements Document Section 2: Glossary The Glossary section contains two tables; Terms and Acronyms. They are listed alphabetically in the appropriate table. 3 Requirements Document Section 3: Referenced Documents This section lists any other documents to which the requirements document refers. These may include the Project Scope Statement, Business Case, Project Charter, Implementation Guide, Technical Standard, etc. Include the Version and Date of the document, if known. Page 6 of 24

7 Business Process: Activities performed to produce a defined business goal. Process Diagrams: Graphically depict the business processes affected by the project outcome. Business Rules: Reflect operational practices and constraints which support the organizational goals. 4 Requirements Document Section 4: As-Is State This section should provide readers with a clear understanding of how things are currently done 1. It supplies the foundation for the redesigned business process ( To-Be State ) and the requirements described in subsequent sections of the Requirements Document. When analyzing the current state and thinking about how do we do our work now, consider and document the following: Define the goals and objectives of the current business process or computer software application. Describe the current workflow in text and/or graphically. o Graphical tools that describe the business process can include context diagrams, task flow diagrams, and swim lane diagrams, or other diagrams as appropriate (See Section 10, Graphical Tools, for additional information). Identify business rules. o Business rules may apply across processes and procedures; consider this when identifying any that may have an impact on the project. o Capture business rules in simple language so that they are easily understood and ensure they are atomic (i.e., cannot be broken down further) so that they are individually verifiable. An example of a business rule is: The patient must present his or her insurance card at each patient visit. Describe tasks and who is responsible. An example of a task and who is responsible is: The Immunization Manager provides valid vaccine identification data. Identify redundancies in the process/data or duplication of effort. An example of data redundancy is: Vaccine definitions are stored in the inventory system and the ER system. An example of a duplication of effort is: Vaccine definitions are entered by the inventory system administrator and the emergency response system administrator. Identify the manual and/or automated processes that might be replaced, changed or improved upon. 1 If the project is creating a brand new process, where no existing process or business rules exist, then that fact should be stated in this section. Page 7 of 24

8 5 Requirements Document Section 5: To-Be State After fully understanding the As-Is task flows and processes, the next step is to think about what will be needed to accomplish the business goals and objectives as identified in the Business Case. When analyzing and describing the future state and thinking about how should we do our work, consider and document the following: Review the goals and objectives of the proposed Business Case. Examine and identify any gaps between the current state and the project goals and objectives. Describe changes that are required to meet the identified gaps. These changes to the current processes or systems may include: o Automation, replacement or modification of existing processes and/or systems o Creation of new processes and/or systems o Integration with other processes or systems (external to the existing processes/systems) Describe the proposed solution ( To-Be ) in text and/or graphically: o Restructured tasks, dataflows and workflows o Graphical tools that describe the business process can include context diagrams, task flow diagrams, and swim lane diagrams, or others as appropriate (See Section 10, Graphical Tools, for additional information). Summarize organizational, operational and personnel development impacts to be expected with the proposed solution. Include the identification of any associated impacts on Business and IT responsibilities. Page 8 of 24

9 Business Requirement: High-level statement of the goals, objectives or needs of the business. Functional Requirement: Describes how an application will work from a user s perspective, mange its information and identify and inputs/outputs. SME: Subject Matter Expert 6 Requirements Document Section 6: Business and Functional Requirements The business and functional requirements are specified in this section of the requirements document. A hierarchy exists between the high-level business requirements and the functional requirements needed to accomplish the project objectives. This hierarchy should be reflected in the way that the requirements are captured so that throughout the project lifecycle each feature can be traced to the business reasons for why it is included, justifying the associated costs. Unique identifiers for each requirement should be used for this purpose, with each level of the identifier indicating the position of the requirement in the hierarchy. Functional requirements typically have one or more associated detailed design requirements that may be identified during the Requirements phase of the project. The level of detail included in this section of the Requirements Document should reflect the intended audience for the document. Where approval of the details has been delegated to the project SMEs, or if the details will not be defined until the Design phase of the project, they may be recorded in an appendix to the Requirements Document or captured separately from this document. Regardless of the project approval approach or project execution plan, detailed requirements must always be captured to support testing and user documentation for the solution. The assignment of categories to the detailed requirements at the time they are captured (e.g., Data, Process, User, Customer, etc.) will aid in the analysis and use of requirements. Following is an example of requirements with their unique identifiers reflecting the requirements hierarchy: Business Requirement: 1. Where threats to the public health may be minimized by the dispensing of mass prophylaxis or medical treatment, the application will allow for the creation of a Campaign to identify the target(s) of response efforts planned by NY State, local Counties and/or Indian Nations within NY. Functional Requirement: 1.1 Each campaign will be defined by a name, a description, the start date of the campaign, and the last date that patient visit records may be updated. Sample Details ('Data' requirements): The Name must be at least 3 alphanumeric characters in length The Name must be unique in the database The first character of the Name must not be a space The Description is mandatory The Description must be at least 10 characters in length. Page 9 of 24

10 Characteristics of Quality Requirements: Unambiguous o Requirements should be written simply and clearly. o They should be easily read and understood by both non-technical business people and technical people in a way that precludes multiple interpretations. o The terminology used should be clearly understood by someone moderately familiar with the business. Unique o Each requirement should be uniquely identified/numbered. o Each requirement should only be included once within the Requirements Document. Complete o Requirements should be kept updated with new, relevant information as the project proceeds. o Requirements should be written using complete sentences that are selfcontained without any missing information. o Each functional requirement should contain all the information needed to describe the outcome that it is intended to address. Consistent o Requirements should not conflict with other requirements or with the expected outcome. o The same business terminology should be used throughout the requirements document. Testable o Detailed functional requirements should be captured at the atomic level; they should be testable or verifiable in isolation from other requirements. o It must be possible to observe and evaluate whether each detailed functional requirement is met. o Requirement identifiers should be structured so that individual detailed requirements can be easily retrieved for purposes of targeted functionality testing. Page 10 of 24

11 Traceable o Unique identifiers for each requirement should facilitate the identification of the high-level business need that the requirement supports. o The schema used to capture the Business Functional Detailed requirement hierarchy should be extendable to support the tracing of design documents, development code and tests to the business needs. Feasible o The requirements should be possible to implement within the constraints of the business. o Technical advisors/team members should confirm feasibility for development and post-development system requirements. o Project manager and business sponsor should confirm feasibility for budgeting, scheduling and post-project business use and support. Design independent o Functional Requirements define what functionality will be provided by the outcome. o Requirements do not specify how functionality can or should be implemented. Use the Active instead of the Passive voice when writing requirements; Passive voice example: The passive voice is to be avoided when writing. Active voice example: Use the active voice when writing. Passive voice example: A report can be run that includes the completed surveys. Active voice example: The application will provide a report that lists the counties which have submitted completed surveys. Textual statements of requirements can be supplemented with one or more diagrams, tables or figures. Page 11 of 24

12 Non-Functional Requirements: Describe the quality and environmental properties that the application must conform to. 7 Requirements Document Section 7: Nonfunctional Requirements The nonfunctional requirements are described in this section of the requirements document. Only describe the requirements applicable to the product/system being specified in the document (i.e., do not list all of the examples below and note N/A for those that don t apply). This list should not be considered complete; there may be other categories that apply to any given project. Consider: Look and feel o Requirements that relate to the appearance/behavior of the interface, for example, corporate branding, colors to be used, etc. Usability o Ease of Use: how quickly or accurately the user can use the product, how much is the casual user expected to remember about using the product, how much and what kind of feedback does the user need in order to feel confident that the product is actually doing what the user expects, etc. o Localization / Internationalization: the way(s) in which the product must support multiple languages, currencies (including the symbols and decimal conversions), regional settings (time zone), etc. Performance o Speed: specifies the amount of time available to complete specified tasks. These often refer to response times. Example: The product will download the new status parameters within 5 minutes of a change. o Precision or accuracy: quantification of the desired accuracy of the results produced by the product. Example: All monetary amounts will be accurate to 2 decimal places. o Reliability and Availability: quantifies the necessary reliability of the product. A nightly backup will be performed on all application files with the ability to restore the data within four hours of a server failure. Page 12 of 24

13 o Robustness or Fault tolerance: specifies the ability of the product to continue to function under abnormal circumstances. The product will provide 10 minutes of emergency operation in the event of a loss of power. o Capacity: specifies the volumes that the product must be able to deal with and the numbers of data stored by the product. The application will support 300 simultaneous users between 9:00 am to 11:00 am. Maximum concurrent users supported during other periods will be 150. o Scalability or extensibility: specifies the expected increases in size that the product must be able to handle. Operational The application will be able to process 50,000 transactions an hour within two years of its launch. o Expected technological environment: specification of the hardware and other devices that make up the operating environment for the system. o External interfaces: description of other applications that the product must interface with. The application will allow search results and associated data to be downloaded to Microsoft Excel. o Architecture/infrastructure: specifies the existing platform or application that will be used. Maintenance The application will reside in the Department s intranet portal and will utilize the Department s Reporting System functionality. o A quantification of the time necessary to make specified changes to the product. New MIS reports must be available within one working week of the date on which the requirements are approved. Page 13 of 24

14 o May also include specification of the intended release cycle for the product and the form that the release will take. Installation The maintenance releases will be offered to end-users once a year. o Description of the installation process or the effort needed to install the product. Supportability The software installation will utilize a wizard that will provide stepby-step instructions. o Specifies the level of support that the product requires and how support will be provided. Support might be built into the product itself or require a staffed help desk. Security o Access: specification of who has authorized access to the product (functionality and data) and under what circumstances that access is granted, and to what parts of the product access is allowed. Only the assigned disease investigation specialist will have the ability to perform case investigation. o Integrity: specification of the required integrity of databases and other files, and of the product itself. The software application will be subjected to a security scan before each release to ensure that Cross Site Request Forgery (CSRF) attacks are not possible. o Privacy: specification of what the product has to do to ensure the privacy of individuals that it stores information about. The product must also ensure that all laws about privacy of individual s data are observed. The system will identify individuals whose personal data may have been compromised. Page 14 of 24

15 Legal o Audit: specification of what the product has to do (usually retain records and document transactions) to permit the required audit checks. Retaining information on who has used the product may also be a requirement. o Compliance: specification of the legal requirements for the system (e.g. tax laws, labor laws, intellectual property, competitor s code, etc.). Personal information will be implemented so as to comply with HIPAA privacy requirements. Documentation Requirements o User Guides / Manuals o Online Help Training o Approach End User and/or Train-the-Trainer o Platform Online and/or Classroom based training Page 15 of 24

16 Project Artifacts: Documented goals and deliverables supporting the execution of a project. 8 Requirements Document Section 8: Requirements Traceability Matrix Requirements traceability ensures that each business need is tied to one or more documented requirements and helps to verify that an application does only what was requested. Performing requirements traceability complies with established industry standards for software development. In addition to the requirements matrix in this section of the Requirements Document, the project should create and maintain a complete project requirements traceability matrix. This matrix shows the relationship between the business/functional requirements and the design and testing project artifacts (e.g., test cases, etc.). The complete matrix traces the deliverables by establishing a thread for each requirement from the project s initiation to the final implementation. This section of the Requirements Document contains the forward traceability from high level source documents (e.g., requirements or business needs stated in the Project Scope Statement) to the requirements specified in this document. Other sources of high level requirements include the Business Case or Project Charter, business policies, standards, legislation and business environmental requirements (e.g., IT architecture) 2. 2 Capability Maturity Model Integration (CMMi), Requirements Development Process Area, Purpose and Introductory Notes, Retrieved 04/09/2012 from Page 16 of 24

17 9 Requirements Document Section 9: Appendix This section may contain supporting information for the contents of the main Requirements Document. Appendices may include additional clarification on the project, program area, data or data model, website links, etc. or supporting project information such as detailed requirements and Business Scenarios (Use Cases). Supported information within the document should include a reference to the associated Appendix. Page 17 of 24

18 10 Graphical Tools This section of the guidance document describes the graphical tools that may be used to describe or supplement textual descriptions of the As-Is State, To-Be State, and/or the requirements statements in your requirements document. The Task Flow diagram: Is read from left to right or top to bottom Uses standard flowcharting tools Builds a step by step picture of the process Represents the sequence of actions and decisions An example of a Task Flow diagram: Page 18 of 24

19 The Context Diagram: Provides a graphical aid in the understanding of the work environment Contains entities (active participants) and transactions Illustrates what happens without focus on the order in which it happens Focuses on the overall environment and objectives rather than the individual parts An example of a context diagram: From Final Recommendation: Core Processes and EHR Requirements for Public Health Syndromic Surveillance, ISDS Meaningful Use Workgroup, January 31, 2011 Page 19 of 24

20 The Swim Lane diagram: Is also called a cross-functional diagram Features division or lanes Each lane is assigned an actor (individual department, division, group, etc.) or a phase or stage Lanes may be displayed in horizontal rows or vertical columns The information is displayed in a logical, chronological order Additional descriptive details can be written in a Narrative lane The Process Model diagram: Is read from left to right or top to bottom Uses standard flowcharting tools Builds a step-by-step picture of the process Includes process inputs and outputs Accommodates a narrative tied to the diagram Each Task in the process represents an action (labels start with verbs) Page 20 of 24

21 An example of a Process Model Diagram: Page 21 of 24

22 11 Requirements Workflow The Task Flow diagram below depicts the flow of activities involved in preparing and documenting the requirements. This flowchart is intended to be a generic process flow that can be applicable to both program and IT initiatives. Work activities are documented via generic business processes. Page 22 of 24

23 12 Glossary Term Assumption Dependency Constraint Business Process Business Requirements Business Rules Detailed Design Requirements Functional Requirements Non-Functional Requirements Process Diagrams Project Artifact SME Definition Factor or condition which is considered to be true or to exist without the need to provide evidence or empirical data. 3 Relationship between conditions, events, or tasks such that one cannot begin or be completed until one or more other conditions, events, or tasks have occurred, started or been completed. 3 Element, factor, or subsystem that restricts an entity, project, or system from achieving its highest goals. 3 A set of related work tasks designed to produce a desired programmatic (business) objective. 4 High-level statements of the goals, objectives, or needs of the enterprise. They describe the reasons why a project has been initiated, the objectives that the project will achieve, and the metrics that will be used to measure its success. 5 A business rule is a statement that defines or constrains some aspect of the business. Rules apply across processes and procedures; they are intended to assert business structure or to control or influence the behavior of the business. The business rules that concern a project are atomic -- that is, they cannot be broken down further. 6 Associated with higher-level Functional Requirements, detailed design requirements address one and only one thing. They are atomic in nature - i.e., they do not contain conjunctions (and, or, etc.). Describe the behavior and information that the solution will manage. They describe capabilities the system will be able to perform in terms of behaviors and operations - specific information technology application actions or responses. 5 Describe environmental conditions under which the application must remain effective or qualities that the application must have. May include criteria related to performance, scalability, security, usability, availability and information architecture. 5 Graphical depiction of the processes, workflows and or tasks. Examples of frequently used diagrams: Context, Task Flow, Swimlane, Process Model, Cause and Effect, Data Flow, Use Case, Sequence. Plans and documented work products produced throughout the life cycle of a project. Examples include the project plans, design specifications, test cases, etc. Subject Matter Expert: project member with business area expertise who contributes to the quality of the project deliverables. 3 Retrieved 04/05/ Public Health Informatics Institute, Taking Care of Business: A Collaboration to Define Local Health Department Business Processes, p.14, June International Institute of Business Analysis, A Guide to the Business Analysis Body of Knowledge (BABOK Guide), Version 2.0, pp. 5,6, Retrieved 04/06/2012 Page 23 of 24

24 Index Appendices, 17 As-Is State, 7 Business and Functional Requirements Overview, 9 Quality, 10 Graphical Tools, 18 Context Diagram, 19 Process Model Diagram, 21 Swim Lane Diagram, 20 Task Flow Diagram, 18, 22 Non-Functional Requirements, 12 Requirements Document Introduction, 5 Referenced Documents, 6 Requirements Gathering, 2 Requirements Workflow, 22 Terminology Definitions, 23 To-Be State, 8 Traceability Requirement Identifiers, 10, 11 Requirements Hierarchy, 9 Requirements Matrix, 16 Standards, 16 Page 24 of 24