In the textual specification, the requirements engineer elaborates the requirements specification as prose (Section 7.3.1). As part of the documentation, the require-ments engineer classifies each piece of information as one of the RE concepts defined in the MIRA artifact reference structure (Section 7.3.2). The requirements engineer documents the requirement sources (Section 7.3.3) and the requirements (Section 7.3.4). The requirements engineer refines the requirements (Section 7.3.5) and documents the refinement links that result from the refinement (Sec-tion 7.3.6). The requirements engineer defines the domain-specific terms used in the requirements by designating glossary terms (Section 7.3.7). A re-quirements engineer or an architect documentrealization linksthat associate requirementswith the artifacts that realize them (Section7.3.8). Figure7.1gives an overview of these actions.
Figure 7.1:Textual Specification
7.3 Textual Specification
7.3.1 Elaborate the Requirements Specification in Prose
The requirements engineer elaborates a coherent set of requirements. The ments engineer documents the requirement sources and their relation to the require-ments. Refined requirements are traced by refinement links. The requirements are documented using prose. For each requirement, the requirements management at-tributes are documented.
Preconditions. As a starting point, the requirements engineer has to identify the problem statement and some initial stakeholders of the system under development.
There may also exist an undocumented candidate list of requirement sources and some draft requirements.
Outcome. The requirements specification contains a set of requirements, requirement sourcesandrefinement links.
Steps.
1. Elicit therequirement sourcesand document them, see Section7.3.3.
2. Elicit therequirementsfrom the requirement sources, classify them, see Sec-tion7.3.2, and document them, see Section7.3.4.
• Concrete techniques, such as interviews, to elicitrequirementsfrom the stakeholderscan be found, for example, in [vL09, p. 76ff].
• Documents may contain requirements that have to be incorporated in the requirements specification. An example is a system requirements specification as an input for a software requirements specification. If the requirement source is a document, classify the contents of this document, see Section7.3.2, and document them according to the classification.
• Requirementspertaining from external systems are often elicited from the responsible stakeholders or documents.
3. Refinerequirements(Section7.3.5) and document therefinement links (Section7.3.6).
4. Theactors of thescenarios anduser functions may impose further re-quirements. Actors therefore have to be added as a (potential)requirement sourceto the list of requirement sources. Anactorcan be astakeholderor anexternal system.
5. Document the refinement of requirements as a refinement link, see Sec-tion7.3.6.
7.3.2 Classify the Elements of a Document
The requirements engineer breaks-down and assigns the contents of a document to the RE concepts defined by the MIRA artifact reference structure.
Preconditions. Unclassified contents.
Outcome. Contents are classified and documented.
Steps.
1. Break down the unclassified contents into individual objects until they match to the definitions for RE concepts provided in the MIRA artifact reference struc-ture.
2. If an object matches a definition, document it with the management attributes that are defined for this RE concept in the MIRA artifact reference structure.
If the object is a requirement, it has to be further classified as a concrete requirement type if possible.
3. If a stakeholder has a concrete requirement on the behavior of a system that matches a definition of one of the functional requirements, classify it accord-ingly as ascenario,interface requirement, oruser function.
The requirements engineer might encounter contents that have to be documented, for example, because they are required in a development activity, and that cannot be matched distinctively to a definition of an RE concept even after breaking them down. Either none or too many definitions may be suitable. This indicates that the re-quirements engineer has to adapt the MIRA artifact reference structure to the project context.
7.3.3 Document a Requirement Source
Preconditions. The requirements engineer identified a requirement source, but has not yet documented it.
Outcome. Therequirement sourceis documented.
Steps.
1. Classify therequirement sourceas astakeholder,external system ordocument.
2. Create astakeholder,external systemordocumentobject and assign a nameto it.
3. Set thestatustoNew.
4. Document thedefinitionof the requirement source.
5. If thenameof therequirement sourcehassynonymsorabbreviations, docu-ment them.
6. Fill in additional information, if required: Forstakeholders, add thecontact information. Fordocuments, addfile information.
7.3 Textual Specification
7. When the information of arequirement sourceis documented, set the sta-tusof the requirement source toIn Consolidation.
7.3.4 Document a Requirement
Preconditions. The requirements engineer identified a requirement, but has not yet documented it.
Outcome. Therequirementis documented as prose, including the management information and trace links to its source and to its design scope.
Steps.
1. Create arequirementobject and assign anIDto the requirement.
2. Document the description of the requirement as prose in thedescriptionfield.
3. Add a rationaleof the requirement, the authorand the priority of the require-ment.
4. Classify each requirement as a scenario, an interface requirement, a user func-tion, if the requirement matches the definition of these requirement types. If it does not match, classify it as a requirement.
5. The requirement source object is referenced in the source field of the requirement. If the requirement source is not documented yet, a new requirement sourceobject has to be created.
6. Document thedesign scopefor eachrequirement:
• Create adesign scope link. Document the system name to which the requirement refers as the sourcein the design scope link. Document the requirement as thetarget.
• Define the design scope as aglossary termin the glossary.
7. Set the status of the requirement toNew.
7.3.5 Refine Requirements
Goalscan be further refined to a set offunctional requirements. These can be manually synthesized intouser functions.
Preconditions. A set ofgoals,interface requirementsorscenarios are defined.
Outcome. Parts of the required behavior of the system are consolidated in auser function. If the complete behavior of that functional aspect is given, the user function can be formalized as an executable formal model, for example, a state automaton.
Steps.
1. Refine goalsto scenarios and interface requirements. This refine-ment requires decisions on the system scope including system boundaries. Use scenarios to define, how the system under development interacts with ac-tors. Useinterface requirementsto define the black-box system behav-ior necessary to fulfill these scenarios.
2. If necessary, refine the required system behavior, the system interfaces or by introducing additional input assumptions (see Section2.3.5.5). Document the refinement in additional scenarios and interface requirements and document therefinement link.
3. Interface requirements and scenarios with the same level of de-tail of their interfaces can be synthesized as a user function. The user functionprovides the user-visible function that is necessary to fulfill these requirements. The user function must fulfill all dedicated interface requirements and scenarios. While interface requirements and scenarios typically only describe a partial system behavior with respect to system inputs and outputs, auser functioncan be used to describe the to-tal behavior of a this set of inputs and outputs. In MIRA, a decomposition of a system into user functions is subject to the decisions of the functional archi-tect, see Section6.3. Hence, also the synthesis ofinterface requirements andscenariosto user functions is subject to these decisions and therefore is performed manually.
4. Document the synthesis frominterface requirements and scenarios touser functionsas arefinement link, see Section7.3.6.
The MIRA approach does not explicitly define the targeted level of detail of the re-finements.
7.3.6 Document a Refinement Link
Preconditions. The requirements engineer documented requirements and re-fined them.
Outcome. Therefinement linkis documented.
Steps.
1. Create arefinement linkobject.
2. Document the refined requirements as thesourceand the refining requirements as thetarget.
3. Document theauthorof therefinement link.
7.3 Textual Specification
7.3.7 Designate Terms Used in the Requirements
“The only way to establish the meaning of a primitive term is to provide an informal explanation of it” [ZJ97]. Zave and Jackson [ZJ97] call documenting the meaning of a term ‘designation’. They argue that a designation grounds formal representations of a requirement in the real world.
Preconditions. Requirements are specified as prose.
Outcome. The meaning of all domain-specific terms that are used in the require-ments is documented asglossary termsorrequirement sources.
Steps. Identify all domain-specific terms used in the description and the attributes of arequirement. Domain-specific terms comprise at least the following: Actors, the design scope and all system stimuli and responses in the description of the re-quirement. All domain-specific terms in the semi-formal and formal representation of a requirement should be added. Domain-specific terms can berequirements sources, or are documented asglossary terms. For example, an actor consti-tutes a potentialrequirement source.
1. Classify the term as arequirement sourceor aglossary term.
2. If the term constitutes arequirement source, see Section7.3.3.
3. If the term constitutes a glossary term, create aglossary termobject.
4. Describe theglossary termby a clear and precisedescription.
5. If required, addabbreviationsandsynonyms.
6. Set thestatusof theglossary termtoIn Consolidation.
7.3.8 Document a Realization Link
This activity documents the realization of functional requirements in subsequent de-velopment artifacts.
Preconditions. Requirements are specified textually, classified and realized in a subsequent development artifact.
Outcome. For each functional requirement, the architect documents realization linksthat indicate which subsequent development artifact realizes the requirement.
Steps.
1. Document the realization of functional requirements as a realization link. Document the requirements as the source and the
development artifact or a part of it as the target. Document theauthorof the link.