DE.2.1. Domain Definition

A Domain Definition establishes the scope of a domain and a justification of its economic viability. It provides a basis for determining, informally, whether a system is properly within that scope.

The Domain Definition does not answer detailed questions of scope, but clearly includes and excludes broad classes of systems and their associated work products. Assumptions of commonality and exclusion identify the common features of systems and work products in the domain, thereby establishing a family. Assumptions of variability identify how systems and work products in the family are distinguished from one another. Justification provides a basis for judging technical and economic feasibility of the domain to evaluate whether there is sufficient confidence in the viability of supporting work-product reuse by the targeted project for a system in the domain.

A Domain Definition consists of the following components:

Domain Synopsis. An informal statement of the scope of the domain.
Domain Glossary. Definitions of significant terminology used by experts in discussing needs and solutions in the domain.
Domain Assumptions. A description of what is common, variable, and excluded among systems in the domain, as reflected in their associated work products.
Domain Status. An assessment of the current maturity and viability of the domain relative to its expected use by the targeted project.
Legacy Products. A representative collection of work products from existing systems in the product line which may be a suitable source of information and raw material for developing the domain.

Every characteristic ascribed to all systems in the domain by the Domain Synopsis must be stated as a Commonality Assumption.

Domain Synopsis

The Domain Synopsis is an informal statement of the scope of the domain. It characterizes systems included in the domain and work products your organization produces during software development.

A Domain Synopsis includes an informal characterization of the systems and work products that make up the domain.

A Domain Synopsis is a simple narrative using terms defined in the Domain Glossary. Example DE.2.1-1. Fragment of TLC Domain Synopsis illustrates a fragment of a Domain Synopsis for the TLC domain. This fragment depicts typical information contained in a Domain Synopsis and the use of terms from the Domain Glossary.

The Domain Synopsis must give an intuitive feel for the definitive characteristics of systems in the domain, as reflected in their associated work products. It should, in itself, adequately describe any existing system (in particular, the system being built by the targeted project).
A term that could have different meanings to different readers may be used in the Domain Synopsis only if it is defined in the Domain Glossary.

Domain Glossary

The Domain Glossary is a compendium of precise definitions for all significant terminology used by experts for discussing problems and solutions in a domain. This domain terminology is organized into a taxonomy of terms.

A Domain Glossary has two parts:

A set of standard terms and their definitions
A list of references to external sources which define and elaborate on relevant topics and terminology

A reference to an external source is written using an accepted documentation style for a reference (e.g., author-date). Standard terms are defined in alphabetical order using the following forms:

Term 1:: definition (source)
Term 2:: (1) first definition (source); (2) second definition (source)

The source of the term's definition (source) is listed after the definition. Example DE.2.1-2. Fragment of TLC Domain Glossary illustrates a fragment of a Domain Glossary for the TLC domain. This fragment depicts typical terminology needed to discuss systems, problems, and solutions in the TLC domain.

The Domain Glossary must contain precise definitions of all significant terminology used by domain experts for discussing the requirements or engineering of systems in the domain or their associated work products.
Any term used in a definition that could have different meanings to different readers must also be defined.
All independently-used terms that are generalizations, specializations, or components of defined terms must also be explicitly defined.
Terms defined in the Domain Glossary must be sufficient for a domain expert to give an accurate description of any existing system and the system being built by the targeted project.

Domain Assumptions

Domain Assumptions describe what is common to all systems or their associated work products in the domain and in what significant ways those systems and work products vary and can be distinguished. These assumptions determine, informally, whether a system, as represented by a set of work products, is within the scope of the domain.

There are three types of assumptions:

Commonality Assumptions. A set of assumptions about the characteristics that are common to all systems in the domain and their associated work products (commonalities).
Variability Assumptions. A set of assumptions about the characteristics that distinguish systems in the domain and their associated work products (variabilities).
Exclusionary Assumptions. A set of assumptions about the characteristics of systems and their associated work products that are outside the scope of the domain (exclusions).

Every assumption is composed of a description and justification.

Assumptions may also be elaborated with associated, subordinate assumptions. For example, a commonality assumption may have specific variabilities associated with it. Similarly, a particular resolution of a variability assumption can be thought of as characterizing a subfamily of the product family. The subfamily then may have additional, more specific commonalities and variabilities that further distinguish the members of the subfamily.

An assumption description and justification are informal text. Assumptions which elaborate another assumption should be presented in adjacent, indented text. Examples DE.2.1-3. Fragment of TLC Commonality Assumptions and DE.2.1-4. Fragment of TLC Variability Assumptions illustrate fragments of some commonality and variability assumptions for the TLC domain. The justification provides rationale on why the domain engineers believe the assumption to be valid.

Commonality and variability assumptions must capture all important aspects that are common to all systems in the domain, as represented by a set of work products, and the significant ways in which these systems and their work products can vary. Exclusionary assumptions must not exclude needed capabilities.
Systems and their work products must only vary as implied by the variability assumptions.
A commonality assumption must apply equally well, without qualification, to any system in the domain, as represented by a given type of work product. Systems, as represented by their associated work products, must not violate a stated commonality, either by excluding an included feature in the commonality assumptions or by including an excluded feature in the exclusionary assumptions.
All reviewers must agree that domain experts will consider Domain Assumptions to be consistent and unambiguous, relative to the definitions in the Domain Glossary. A term that could have different meanings to different readers may be used in a Domain Assumption only if it is defined in the Domain Glossary.

Domain Status

Purpose:

Domain Status describes the current technical maturity of the domain that the organization has achieved relative to planned evolution, and assesses the viability of evolution. Of particular concern are unsupported variability assumptions (i.e., default commonalities).

Content:

The Domain Status is an informal characterization of the degree to which Domain Objectives are satisfied by past development. It includes an analysis of how well the needs of the targeted project are being met by the domain.

Form and Structure:

The maturity of a domain can be expressed as limitations in satisfying variability assumptions. Risks can be mitigated by imposing limits on variability assumptions.

Be sure your descriptions of problems and functions characterize the system to be produced by the targeted project.

Legacy Products

Legacy Products provide access to work products from existing systems that may be useful sources of information and raw material for developing the domain.

Legacy Products consists of a representative collection of work products (or portions thereof) from existing systems in the product line to be supported by the domain.

Work products may be physically stored, on paper or in electronic media, or may only be identified by reference when sufficiently accessible in this way (e.g., in an organization's local library or in an accessible repository set up for another, existing domain).
Work products are kept in Legacy Products in the form in which they were produced. Other, consuming activities of Domain Engineering will copy and excerpt or adapt these work products, as needed, in order to create reusable assets.
The work products comprising the Legacy Products are organized in a suitable manner to provide access by other Domain Engineering activities to a particular system's work products or to individual work products of a particular type.

Step: Define Domain Informally

Each work product in Legacy Products must come from an existing system that was determined to be in the domain.

PROCESS DESCRIPTION

The Domain Definition Activity consists of the five steps shown in Figure DE.2.1-1. Domain Definition Process.

Procedure

Follow these steps for the Domain Definition Activity.

Create a description of the domain, characterizing key technical objectives of included systems.

Domain Plan: Domain Objectives

Domain Definition: Domain Synopsis

Step: Establish Standard Terminology

Start with a one-sentence description of the family of systems that constitutes the domain.
Refine the Domain Synopsis to two pages, at most, of intuitive and not overly-restrictive text. Impart, concisely, an informal but complete sense of the domain in the first paragraph. Try to focus on the essential nature, scope, and variety of systems in the domain.
Characterize the type of problem that systems in the domain solve, and the external environment (i.e., devices, systems, and users) with which systems interact. Describe the observable behavior that systems exhibit in solving the problem. You might also establish significant constraints concerning how the systems operate in terms of performance, reliability, or distribution concerns.
Cover the primary functions performed by every system in the domain and any important functions performed by only some systems. Maintain a black-box perspective when describing functional aspects of the system.
Be sure your descriptions of problems and functions characterize the system to be produced by the targeted project.
Use terms defined in the Domain Glossary to keep the Domain Synopsis short.
If the domain (e.g., process control systems) is based on formal theories that provide experts with a common language of communication about problems, refer to those theories in the Domain Synopsis.

Action:: Create definitions of all significant terms used by domain experts in discussing the requirements or engineering of systems in the domain or their associated work products.
Input:: Domain Definition: Domain Synopsis
Result:: Domain Definition: Domain Glossary
Heuristics:: Maintain term definitions in alphabetical order for ease of reference. Provide cross-references to related terms.
Use definitions from standard glossaries where possible. Make note of such sources in each definition for future traceability.
Make definitions as precise as possible.
Make sure that all terminology used in the Domain Synopsis is defined in the Glossary.

Step: Establish Domain Assumptions

Create lists of the assumptions that allow you to think of the envisioned set of systems as a family and the assumptions that allow you then to distinguish among them and their associated work products.

Domain Definition: Domain Synopsis
Domain Definition: Domain Glossary

Domain Definition: Domain Assumptions

Step: Assess Domain Status

State only those assumptions that affect the system software and associated delivered products (e.g., documentation, test support).
Initially, concentrate on assumptions related to system functionality. Expand your focus to design issues and to assumptions about related work products.
Assumptions often come from knowledge or analyses of work products of Legacy Products. If some assumptions relate only to a particular type of work product, then group those assumptions apart from the generally more applicable assumptions.
To create a preliminary set of assumptions:
- Create a commonality assumption for each characteristic specified in the Domain Synopsis that is shared by all systems in the domain.
- Create a variability assumption for each characteristic specified in the Domain Synopsis that is not shared by all systems in the domain.
- For each term in the Domain Glossary, determine whether the term indicates a commonality or a variability among systems in the domain. Create an assumption accordingly.
Make variability assumptions precise by indicating the type of decision the application engineer must make to resolve the variability. It is not sufficient to note only that some characteristic varies. You must establish how much flexibility the application engineer needs to characterize different systems adequately.
Elaborate commonality assumptions to uncover specific variabilities assumptions associated with them. This will more precisely characterize a subset of the product family.
Elaborate variability assumptions to find more specific commonality and subsequent variability assumptions that further distinguish members of the subfamily.
Compare the characteristics of existing systems to facilitate the identification of common features and variations.
Distinguish between system-generation-time and run-time variations when developing assumptions about variable aspects of the domain. Treat a run-time variation that is characteristic of all systems in the domain as a commonality.
Use exclusionary assumptions to clarify a domain's boundary. Do not enumerate every type of system or function that is outside the domain. Rather, exclude explicitly those functions or characteristics that a domain expert might incorrectly assume to be part of a system when reading the Domain Synopsis. Thus, you can answer the question of whether a particular system belongs within the domain more directly by checking the exclusions. Exclusions often result from a viability analysis of the domain.
State unresolved issues of functionality, design, etc., from the targeted project as variability assumptions. This will help you identify the full range of existing work products that might meet an anticipated Application Engineering need.

Evaluate the technical maturity of the domain in terms of targeted project needs, Domain Objectives, and plans for domain development.

Domain Plan
Domain Definition: Domain Assumptions

Domain Definition: Domain Status

Step: Identify Legacy Products

Domain Status must result in an endorsement of and commitment to a specific domain scope (set of assumptions). This endorsement comes from targeted project needs, as tempered by the intuitions of experienced personnel, and resource constraints (e.g., what products are available). In other words, you should assess which Domain Assumptions are currently satisfied versus which should be satisfied. Of those which should be satisfied, assess which can be satisfied using existing resources and which can be satisfied using resources presumed to be available at some future date. This information should help you determine whether the features associated with each assumption are implementable, and the corresponding risk.

Identify existing systems in the product line that are considered representative of the domain and whose work products may prove useful as sources of information and raw materials in developing the domain.

Domain Synopsis
Domain Assumptions

Domain Definition: Legacy Products

Use the Domain Synopsis as a guide to select existing systems that are within the domain (or subsystems that would be parts of such systems).
Based on Domain Assumptions, identify work products (or fragments, if appropriate) from these systems that reasonably satisfy some or all of the Domain Assumptions.
Create a brief description of the selected systems and work products as a guide to their use as a source of information and raw materials by other Domain Engineering activities.

Risk Management

There is a lack of critical expertise.

The Domain Definition cannot be completed or there is unacceptably low confidence in the results.

Commit time and resources to acquiring the expertise.
Restrict Domain Assumptions sufficiently to reduce the need for expertise.

The scope of the domain may be too narrow, precluding useful variations.

Opportunities for additional projects are lost.
Application engineering projects miss opportunities for reuse.

Review the Domain Definition with management and experienced engineers to identify additional variations.
Include unresolved issues from the targeted project.

The scope of the domain may be too broad.

Resources are misapplied to solve an unnecessarily general problem; the result will be parts that require so much hand-tailoring that the cost of reuse becomes higher than that of developing parts from scratch.

Review the Domain Definition with management and experienced engineers to identify under-constrained Commonalities.
Focus variations on the needs of the targeted project.

Domain Assumptions are too precise or too vague.

Flexibility is reduced unnecessarily, or key decisions are left to the discretion of domain engineers.