ICS 121: Specification vs. Design

User needs are what the customer and other stakeholders say they want.
The statement of user needs just captures information about the problem, it does not propose or promise any particular solution.
User needs can be fairly informal English text. Some types of structured text (e.g., user stories or a glossary) are very useful.
More formal notations can also be used to precisely describe the context and the problem. E.g.:
- a UML use case diagram can show types of stakeholders and ovals for user stories
- a UML class diagram can show real-world objects and their relationships
- a UML state diagram can show the states of real-world objects
You did a statement of user needs in Lab 2.

A software requirements specification (SRS) is a technical document that describes in detail the externally visible characteristics of a software product.
A SRS is not the same as a statement of user needs. The SRS says what the product will be.
- The product may do less than what customers want
- The needs of different potential customers may conflict
- The product may do more than what any one customer wants
The SRS can include English text, structured text, diagrams, tables, formulas, rules, etc.
Parts of the SRS include:
- Environmental requirements: OS, platform, interoperability, standards, etc.
- Non-functional requirements: security, usability, efficiency, etc.
- Feature specifications: precisely describe each feature
- Use cases: examples of how a user accomplishes a goal by using one or more features
Template for SRS

A design document outlines an implementation that will satisfy the requirements of the SRS.
There are many aspects of the system that need to be designed:
- Division of the system into components
- Communications, APIs and dependencies between components
- Classes, attributes. operations, and relationships within each component
- Data representation in the database or files
- Behavior of each system component
- Internal APIs for testing and later extensions (e.g., future subclasses)
- Outline key algorithms and conditions that affect the overall design (otherwise leave that for implementation)
Many notations are used in design
- Plain English or structured English
- Many types of UML diagrams
- Tables, formulas, pseudo-code, other diagrams as needed

The SRS describes precisely what the system will do.
- It is based on user needs
- It sets the stage for design and system testing
Customers should be able to review the SRS and help validate it.
- Validation of requirements is checking the written requirements against (unwritten) reality
Design outlines how the system will work.
- It is based on the SRS
- It sets the stage for implementation and integration testing
Usually only members of the development team need to review the design.

Both SRS and Design documents are technical documents that need to be precise.
- In fact, sometimes the same notation is used for multiple purposes
Both need to be reviewed by several stakeholders and defects must be corrected.

V-shaped waterfall
User needs gathers information for the SRS
The SRS describes the system that will satisfy (some) user needs, sets the stage for design, and will be tested in system test.
The design documents outline how the system will implement the features specified in the SRS and sets the stage for integration test.

The 4-C's of requirements:
- Clear: Understandable so that all stakeholders can participate in validation and all developers know what to build and test
- Concise: Short requirements are more understandable and maintainable. And, they can often be more precise when you use formalisms.
- Correct: Incorrect requirements will lead to reduced revenue, or major rework.
- Complete: Incomplete requirements also leads to major rework and last-minute schedule changes.
The specification should not bias the design or implementation.
- Don't get ahead of yourself, you will do design later
- Design details make the SRS harder for non-technical stakeholders to understand and validate
- Internal details of the design are irrelevant to system test
- You may come up with better ideas for the design later, you do should not have to change the SRS unless your goals for the product change