requirements documentation

Requirements Documentation : 

Requirements Documentation Conventions and Standards

Purpose of the SRS : 

A Requirements Baseline means we have established, in the users language, a statement of the system functionality and operating constraints Purpose of the SRS SRS Business Vision / Roadmap Informal Requirements Feasibility/Cost Analysis Project Plans Requirements Analysis Contract(s) Customers Business Stakeholders QA Requirements Analysts Architect Users Everybody depends on it!

Problems with Natural Language : 

Problems with Natural Language Lack of clarity Precision is difficult without making the document difficult to read Example: “user friendly”; this is subjective. But trying to express a “friendly” UI would probably take a lot of language. Requirements confusion Functional and non-functional requirements tend to be mixed-up Example: “The system may only have open up to 10 files maximum” – functional or nonfunctional? And what happens when that threshold is reached? Requirements amalgamation Several different requirements may be expressed together Example: “The user shall be able to search either all of the initial set of databases or select a subset from it”

Problems w/ Natural Language : 

Problems w/ Natural Language Ambiguity The readers and writers of the requirement must interpret the same words in the same way. NL is naturally ambiguous so this is very difficult. Example: “The status message will be placed 100 pixels above the origin of the screen” What is the origin here? What are the reference points for the pixel measures? Over-flexibility The same thing may be said in a number of different times in the specification Same problem when cutting and pasting code – when you make a copy of some thing, it is hard to maintain all copies. Lack of modularisation NL structures are inadequate to structure system requirements Humans tend to modularize in a document outline, this is different than a problem space partitioning you may want to adopt.

Using Natural Language : 

Using Natural Language Some Solution Guidelines for Natural Language: Decide on a standard format and use it for all requirements Use language in a consistent way. Use shall for mandatory requirements, should for desirable requirements. Use text highlighting to identify key parts of the requirement Avoid computer jargon; express user reqs in the user’s language Alternatives to Natural Language RUP: Use case models + Glossary + Supplemental spec Blurs the line between formal requirements and analysis XP: User Stories + Planning Game Get software working first as a communication vehicle Structured Natural Language Forms, PDLs, etc. – Varying levels of language structure Formal Requirements Specification Precise mathematical expression – used in mission critical systems

Structured language specifications : 

Structured language specifications Structured Natural Language A limited form of natural language may be used to express requirements This removes some of the problems resulting from ambiguity and flexibility and imposes a degree of uniformity on a specification Often best supported using a forms-based approach Forms Example Template: Definition of the function or entity Description of inputs and where they come from Description of outputs and where they go to Indication of other entities required Pre and post conditions (if appropriate) The side effects (if any)

Form-based specification : 

Form-based specification Starting to look like design eh?

Requirements Standards : 

Requirements Standards IEEE 830 A “Best Practices” document for Requirements Do not embed design in the requirements spec Do not embed project requirements in the spec Joint ownership between customer and supplier Supports evolution (Only “anti-waterfall” statement; embrace change) Prototyping - Use as an elicitation technique Historically well-known for its language – “shall” Related to Software Lifecycle Process std IEEE 12207 SRS Benefits: Basis for agreement between customers and suppliers Reduce development effort Complete an SRS before design and find problems earlier Basis for estimating costs and schedules Baseline for V&V Facilitate transfer: To users, new devs, new technology Basis for enhancement

Requirements Standards : 

Requirements Standards IEEE 830 SRS Format Section 3 is the main body State these in concert with the notion of a “good” SRS Cross-referenced against earlier spec documents Uniquely identifiable Attention to organization Section 3 should address: External interfaces Functions Performance requirements Logical database reqs Design constraints Software System attributes Supporting Information TOC Index Appendices IEEE830 provides several SRS templates to choose from

Requirements Standards : 

Requirements Standards Other standards: Electric Power: EPRI Aerospace: Onboard systems software: RTCA DO-178B/ED-12B European Space Agency: ESA PSS-05-01 to 05-03 AS9006 Aerospace Software Supplement for AS9100A Medical: Medical Electric Systems: IEC  60601-1-4 Note these tend to be either vertical system-standards or general standards developed by a vertical organization Also, other standards under Quality Mgmt discuss Reqs EIA 632 ISO 9000 ANSI/IEEE  7.4.3.2

Dr. Gary’s Tips : 

Dr. Gary’s Tips We need some Natural Language Use Cases and User Stories focus primarily on the end user functional requirements Formal specifications expensive and change-resistant The use of NL needs to be structured Like other techniques, you can be more imprecise (or “conversational” at the beginning, but you need to be more exact as you get to the final SRS What does done look like? That age-old answer: “it depends” How the doc will be used? Rephrase the question: “What do your stakeholders need to proceed with the requirements?” Embrace change: good philosophy, tough to manage