Requirements documentation: a systematic approach

Unless you have a complete and precise description of a product’s requirements, it is very unlikely that those requirements will be satisfied. An incomplete or inconsistent requirements document can mislead developers. A collection of statements in English, or some other natural language, cannot be checked for completeness and will not be precise. Even if you translate an informal requirements statement into a mathematical language, and show that the result is complete and unambiguous; the original may still be faulty. This talk describes a sound procedure for documenting requirements one that lets you know when your document is complete and consistent. Documents produced by following this procedure can be reviewed by potential users and specialists and can serve as the input to tools that generate prototypes and monitors. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 2 /45 req_slides_landscape.fm 2 /2/03 The Responsibilities of an Engineer An Engineer’s responsibility includes making sure that products are “fit for use”. This requires precise, detailed, communication with the application experts. Communication must be on the basis of a written statement of the requirements: • that can be read and analysed by both users and implementors • that can be used to evaluate the product after completion • that can be used to settle disputes after completion. • that can be used to communicate the eventual changes that are required. No engineer can fulfil his/her responsibilities without such a document. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 3 /45 req_slides_landscape.fm 2/2/03 A Small Horror Story that is Close to my Heart. Product: A motion sensitive pacemaker Situation: Rarely needed, only if heart rate drops to low for activity level. Software: Measures acceleration, estimates activity level, computes expected heart rate, intervenes (causing some discomfort) if rate is lower than expected. • Parameters include resting heart rate and slope of curve. • Resting heart rate can only be set in multiples of 10. This does not meet patient’s requirements. Software requirements were never documented or reviewed by users. Those with a resting heart rate between the possible set points will have to chose between too low and too high. Some of the parameters not meaningful to doctors they use default values. No instructions are given to doctors. I hope that this would not have happened if the planned behaviour had been communicated to doctors and they had reviewed them carefully. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 4 /45 req_slides_landscape.fm 2 /2/03 Why Programmers Should Not Make User-visible Decisions Context: • U.S. attack aircraft with two altimeters; pilot can choose the preferred one • Software checks functionality, switches to other device if readings are unreasonable. Question: What should we do if both altimeters are broken? • Programmer asks pilot: What is average altitude of flight? • Program displays the average altitude when no altimeter is functional. The answer to the real question: Flash Pull-Up cue. The result: Pilots have been trained to watch for “average” altitude appearing for more than a few seconds and told to “pull up” if that happens. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 5 /45 req_slides_landscape.fm 2 /2/03 A Small Success Story PROSYS: A small Software Company in Germany Developer and customer sit down and complete • A list of quantities of interest • A set of tables They check for completeness and consistency. They initial the tables. The tables are used to develop the software. 60% of the code can be generated by simple tools. The software is almost right. There is no doubt about who pays for each “fix”. The Secret: The tables constitute a precise requirements document. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 6 /45 req_slides_landscape.fm 2 /2/03 Building on Rock vs. Building on Sand My basic assumptions: • Software that is “almost right” is wrong. • Imprecisely defined notation leads to software that is almost right. • Notations used in tools are precisely defined, but that definition may not be clear and simple. (e.g. Statecharts) • Mathematical definitions of software notations are essential, but must be simple and based on standard mathematics. • Mathematics can be simple and not fundamentally new. • Undefined Modelling Languages (UMLs) are quicksand. • Documentation can be useful for design, review, implementation, testing and maintenance. • More practical difficulties with documentation result from issues about the required content of documents than from issues about format. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 7 /45 req_slides_landscape.fm 2/2/03 What Could we do with Mathematical Descriptions of software? (1) Describe software products that we already have so that people can answer questions about them without reading the code. (2) Write specifications for software products we do not yet have so that the programmers and clients can reach agreement on the requirements. (3) Verify that a product meets its requirements (testing and/or inspection). (4) Build tools to check specifications (5) Build tools to simulate systems and check systems. What are the Acceptance Criteria for the Descriptions? (1) Descriptions must be easier to understand than the code. (2) Documentation must state the requirements in a way that does not restrict the solutions unnecessarily. (3) Testing and proof could eventually be automated. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 8 /45 req_slides_landscape.fm 2/2/03 Are Programs Different From Other Engineering Products? Before we had computers, engineers used classical mathematics to describe and analyse their products. In Computer Science, most researchers have turned to newly invented “languages”. We are using software to replace conventional products. Why can’t we simply go on using the mathematics we used to use? • Wrong Answer: Conventional products are inanimate objects. • Wrong Answer: We need to describe the procedure followed by the program. • Right Answer: The functions have many more points of discontinuity. We will return to this point later. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 9 /45 req_slides_landscape.fm 2/2/03 The Purpose of a Requirements Document We are talking about a technical document written for developers. • Requirements documentation should not be a sales pitch! • Requirements documentation should not be an introduction. • Requirements documentation should serve as a reference document during development. • Requirements documentation should prevent programmers from taking unilateral decisions that should be made with others. • Requirements documentation should be used for design reviews. • Requirements documentation should be used for test case generation and test result evaluation. • Requirements documentation should be used, and kept up to date, during maintenance. • Requirements documentation can be modified to specify revisions. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 10 /45 req_slides_landscape.fm 2 /2/03 The Goals of the Requirements Phase A. Decide what to build before starting to build it: • Make “what decisions” explicitly before design, not implicitly during design. • Make sure you build what is needed. • Allow future users, or representatives, to comment before the product is built. B. Provide an organised reference document for the software developers: • Provide accurate, consistent information. • Answer constraint questions only once. • Relieve them of any need to decide what is best for the user. • Compensate for their ignorance of the application environment. • Give them the information needed to make good design decisions. • Allow her to make accurate estimates of time and resources needed. C. Allow for personnel turnover. • Record what has been learned for future replacements. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 11 /45 req_slides_landscape.fm 2/2/03 The Goals Of The Requirements Phase D. Provide a reference document for a Quality Assurance Group • Test design should not depend on program. • Authority required:---Q.A. and programmer may disagree. E. Specify all constraints on the implementation • Know what you're up against. • Have some “protection” against customer changes. • Be able to judge feasibility and cost. F. Specify constraints for future revisions. Note: A requirements document is not a “write, use (at most) once and discard” document. A good document, properly maintained, will be useful until the product is discarded and possibly for the next product. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 12 /45 req_slides_landscape.fm 2/2/03 Writing Down Requirements The most costly errors are those made early in the process Early errors are the hardest to change. Misunderstandings about requirements lead to early mistakes. Programmers need to be told what is needed now; they must also be told what is subject to change. Requirements must be subject to review. Safety reviews of software should be based on the statement of requirements, not the code. Maintenance actions must be based on requirements. None of this is possible unless we have a written statement to work with. That written statement must be precise and complete. That written statement must be organized for reference so that information appears in a specified place and will not be missing or (almost) duplicated. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 13 /45 req_slides_landscape.fm 2/2/03 The Two-variable Model The “traditional model” of a hardware/software system is based on two assumptions. • The system has inputs and outputs. • The outputs are a mathematical function of the inputs. In this model, the inputs are the actual physical inputs to the hardware/ software system. The