Specifications & Requirements
1 How to Write Software Requirements
Software requirements must be written in adherence to very specific characteristics. It must be assumed that the author of the requirement is not necessarily the developer of the software. The characteristics of well written requirements include:
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.
Each team must decide how to label each development element. For example, if you have two databases, each must have a unique name, which must be included in your glossary. Each requirement must consistently identify/reference each development aspect.
The team must decide upon the format for each requirement so that they all look the same, and contain the same requirement-ese. For example, using the word must vs shall.
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.
No matter who reads it – the take-away understanding must be identical.
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.
Every requirement will be validated by a unit test case, to be written in Lab 3.
Each unit test will verify/validate correct implementation of a single requirement. A test case is not intended to assess multiple development aspects. The word “and” should therefore not be used! Nor should there be commas! This style of writing indicates that multiple elements are included.
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.
No bells and whistles – unless of course they need a bell or a whistle. This is analogous to a contract. Promise no more than what is necessary. Remember the three goals of a project, and time is money.
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.
Only include words that are needed for understandability. For example, words such as intuitive, effective, cute, or quick are vague descriptors. Requirements are written for skilled engineers.
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.
Requirements are written for skilled engineers. You are able to assume that they know how to code well, and how to use best practices, or they should not be doing the job. For example, do not state that “The user must be able to submit the completed form by pressing the submit button at the bottom of the page.” The web-developer can determine that a button is needed and that it should be at the bottom of the page. Such a requirement tells the reader that the page has already been developed and the requirement was written after the fact.
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.
Do not include requirements that your team is not capable of completing due to lack of knowledge or skill. If you know that the needed hardware is too expensive, write requirements to model or simulate the functionality.
Complete. (standalone) The stated requirement is complete and does not need further amplification. The stated requirement will provide sufficient capability.
A unit test case can be written to evaluate this requirement and only this requirement.
By the end of the first week of this module, each student must write a single requirement for evaluation by their team and the instructor. It will be evaluated based upon its adherence to the stated characteristics of a well written requirement. It will also be valuated based upon how it pertains to the prototype.
2 Why Requirements are Necessary
The technical writing goal for this module is to write high quality specifications and requirements. Lab 2 will be due at the end of this module. The lab is comprised of three Sections. Each team member is expected to author an individually written submission, for Sections 1 and 2. Each team is expected to co-author Section 3.
Consider this scenario…
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.”
Typical of many students, extra work is expected to result in extra credit toward any assignment grade. Making the work extra pretty, or extra detailed, or showing every tiny step is perceived as an opportunity to prevent point deductions. I, personally, have been subjected to multiple paragraphs on exam answers – that say NOTHING.
In industry – a primary expectation is that the company will survive to see another day, and its employees to see another pay check.
Reminder – Three Goals of a Project:
- Stay on schedule
- Stay on (or under) budget
- Solve the problem to the customer’s satisfaction
The customer. We spent last semester appreciating the customer’s problem domain. You each have a mentor who is now the customer. By the end of this Module (schedule-wise), the customer must agree that you have prepared a document outlining a development process that will solve their problem to their satisfaction.
The Requirements Specification document developed in this module is representative of industry standards. It is a two-way agreement of the work to be done. It confirms your understanding of what the customer thinks he/she wants, and confirms the customer’s understanding of what you plan to deliver.
3 Requirements vs. Specifications
Some definitions to clarify the difference:
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.
The development of good requirements is essential to quality product design. They must be written clearly, concisely, and simply.
The types of requirements include:
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.