CS 411W - Notes Product Development Documentation

CS-411W Product Development Documentation The professor gave the class a set of requirements to meet. One student failed the assignment. He argued to the professor that not only did he do all those requirements but that he did extra work and added some really neat functions. "Exactly," replied the professor, "you didn't meet the requirements."

Management Plans Requirements Specifications Test and Acceptance Plans Top Level Design Test and Acceptance Procedures Detailed Design Software Design Hardware Design Installation Design Users Manuals Maintenance Manuals Development Phases and Supporting Documentation

REQUIREMENTS VS. SPECIFICATIONS DEFINITIONS Requirement. A statement identifying a capability, physical characteristic, or quality factor that bounds a product or process need for which a solution will be pursued. Specification. A document that fully describes a physical element or its interfaces in terms of requirements (functional, performance, constraints and physical characteristics) and the qualification conditions and procedures for each requirement. System. The top element of the system architecture, specification tree, or system breakdown structure that is comprised of one or more products and associated life cycle processes and their products and services. DEVELOPING REQUIREMENTS Development of good requirements is essential to quality product design Basics of well defined requirements are clarity, conciseness and simplicity In the words of Albert Einstein: "When you are out to describe the truth, leave elegance to the tailor".

TYPES OF REQUIREMENTS Functional requirements describe the capabilities of the product or system (what the system must do). Performance requirements describe how well the product or system must perform a function. Performance requirements complement the functional requirements, and these are sometimes combined into single requirements. Interface requirements specify how the system will interact or interoperate with an adjacent system. Safety, Quality, Reliability, Maintainability, etc. (the “ilities”) – this set of requirements relate to overarching system questions, such as “how long will it work without breaking” and “can it hurt me”. Some “ility” requirements can be decomposed into specific functional and performance requirements. Others essentially put constraints on the design, implementation, manufacturing, or production processes.

REQUIREMENTS CHARACTERISTICS Consistent. The stated requirement does not contradict other requirements. It is not a duplicate of another requirement. The same term is used for the same item in all requirements. Unambiguous. Each requirement must have one and only one interpretation. Language used in the statement must not leave a doubt in the reader's mind as to the intended descriptive or numeric value. Verifiable. The stated requirement is not vague or general but is quantified in a manner that can be verified by one of these 4 alternative methods: inspection, analysis, demonstration or test.

REQUIREMENTS CHARACTERISTICS Necessary. The stated requirement is an essential capability, physical characteristic, or quality factor of the product or process. If it is removed or deleted, a deficiency will exist, which cannot be fulfilled by other capabilities of the product or process. Concise (minimal, understandable). The requirement statement includes only one requirement stating what must be done and only what must be done, stated simply and clearly. It is easy to read and understand Implementation free. The requirement states what is required, not how the requirement should be met. A requirement statement should not reflect a design or implementation nor should it describe an operation. However, the treatment of interface requirements is generally an exception. Attainable. (achievable or feasible). The stated requirement can be achieved by one or more developed system concepts at a definable cost. This implies that at least a high level conceptual design has been completed and cost tradeoff studies have been conducted. Complete. (standalone) The stated requirement is complete and does not need further amplification. The stated requirement will provide sufficient capability.

PRODUCT SPECIFICATION OUTLINE 1. Introduction 1.1 Purpose Describe the purpose of the Product Specify who the intended audience is. 1.2 Scope Identify the product to be produced by its name. Explain at a very high level what the product will do and what it won't do. Describe the application of the product, i.e., its objectives, relative benefits, and goals as precisely as possible. 1.3 Definitions, Acronyms, and Abbreviations List all definitions, acronyms and abbreviations used in this subsection. 1.4 References Provide a complete list of all documents referenced. Identify each document by title, report number or version id, data, publishing organization, etc. 1.5 Overview · Describe what the rest of the Product Specification contains. · Describe how the Product Specification is organized.

PRODUCT SPECIFICATION OUTLINE (CONT) 2. General Description 2.1 Product Perspective Identify if the product is totally self-contained or part of a larger system or product line. If the product is part of a larger system, then describe the function of the larger system and how this product will interface to the larger system. This is at a high level. 2.2 Product Functions Provide a summary of the functions that the product will provide. Do not go into detail at this point. Detail follows in section 3.1. Use diagrams to provide a high-level representation of the high-level summary. 2.3 User Characteristics Describe general characteristics of the users that will affect the functionality of the product. Things such as educational level, technical expertise may affect general functionality of the product. 2.4 General Constraints Describe items that will limit the developer's options for designing the system. Examples are regulatory policies, audit functions, hardware limitations, interfaces to other applications, safety and security considerations, etc. This section should not be used to document design constraints. 2.5 Assumptions and Dependencies Describe any assumptions that have been made and that would affect the requirements if they turned out to be false. An example assumption is that a specific piece of hardware will be available before the product goes into testing. Describe any dependencies that exist. A dependency may be that a specific subsystem, hardware, or software component exists.

PRODUCT SPECIFICATION OUTLINE (CONT) 3. Specific Requirements This section contains the detailed requirements. Each requirement should be a single statement that describes a key attribute of the product. Requirements should be grouped under functional, performance, design constraints, and non-functional requirements. Requirements under each subsection should be further grouped into functional areas. A functional area is a grouping of related requirements that provide related functionality. For example, in a word processor, the requirements for the grammar checker may be grouped under the functional area grammar checker. 3.1 Functional Requirements State each functional requirement as an individual statement with a unique identified Functional Requirement Functional Requirement 2

PRODUCT SPECIFICATION OUTLINE (CONT) 3.2 Performance Requirements Describe any performance requirements in this section. Performance requirements should possess numeric boundaries, etc. They should be stated in measurable terms. Each requirement should be stated as an individual statement with a unique identifier Performance Requirement Performance Requirement Design Constraints This section should identify any design constraints that have been imposed by other standards, hardware limitations, customer requirements, etc. 3.4 Non-Functional Requirements Describe the non-functional requirements that characterize the function of the product. Examples of these are security, maintainability, and reliability. Place those that are pertinent to your product in this section Security Maintainability Reliability Appendix Put items that provide additional information, but do not belong in the body.

PRODUCT DEVELOPMENT EXAMPLE