Forest concepts
In this section, a high-level concept overview of the proposed approach is presented. The main goal is to create and maintain documentation of systems. Information artefacts that are to appear in this documentation should be entered in a structured repository, including relations between these artefacts. Various checks can now be performed to ensure the information in the repository is consistent and complete.Documents (e.g. a requirements specification or a design document) can now be generated based on the information in the repository. The contents of these documents can vary per stakeholder: an architect is typically interested in the system as a whole on a high level of abstraction, whereas a developer or construction engineer is interested in a only part of the system but including all the details.
While generating documentation, the results of the checks performed can be added to provide information about the state of the system. This state information can be represented by means of small icons, so-called decorators, in the margin of each paragraph. For example, in a requirements specification, each requirement description can contain such a decorator indicating whether this requirement can be traced to a design artefact or to an implementation (i.e. the requirement is satisfied) at the time of generating the document. Having state information included in the documents implies that documents are no longer intended for long-term use. Hence, documents should be generated when information is needed, to ensure having the latest information on the respective artefacts.
Having a system described according to the proposed structure (explained in more detail next), allows for easy reuse of information. Projects in the same domain or for the same customer can share e.g. a common set of requirements once these are stored in a reusable repository.
Repository
This subsection explaines the concepts of the repository (i.e. the meta model) needed to store the information artefacts and relations. First, four basic element are introduced, which can be used to create a simple repository. By means of eight additional elements, explained next, the repository can be given more functionality. Details of the artefacts are described in the author's thesis.Requirement
Since all system development starts with a list of requirements, these should be stored in the repository. A requirement typically consists of a title and a description. Optionally, several attributes can be set. A requirement artefact does not necessarilly represent requirements to the top-level system artefact, but may also represent the needs resulting from design decisions in a lower level subsystem.System
The system element represents a design artefact, typically consisting of a title, a description and a motivation. A system can contain requirements, other systems, atoms (representing a part of the implementation), and delegations (realizations of relations between artefacts). Artefacts can be reused by declaring a system abstract and extending this system, as illustrated in Figure 1. This obliges the extending system to implement all requirements of the abstract system as well as to provide subsystems and atoms similar to the abstract system.
Figure 1: A system extending another, abstract system.
One of the attributes of a system artefact is the location. This relative file path allows to store a system description (i.e. part of a Forest repository) in a separate XML file. When documenting for example a software project, each subdirectory in the source code folder (each package in case of a Java project) may contain a system description in its own Forest repository. At the top-level source directory, a Forest repository should be available containing multiple system artefacts, which only have their location attribute set, referring to another repository in a subdirectory.
Atom
Atoms in the Forest repository represent atomic (indivisible) parts of the implementation and should be used to satisfy requirements. This can be realized by explicitly implementing a requirement or having a requirement delegated to the atom. In case a part of the implementation is meant that is divisible in several parts, a system artefact should be used instead of an atom. Furthermore, atoms can contain references to the file system to actually link to the concrete implementation (e.g. a source file).Alternatively, an atom may be used during the design phase as a placeholder for a subsystem the architect does not want to elaborate in more detail. In a later design phase, the atom can be replaced by a system containing more details. The advantage is that the atom can already "implement" requirements such that the first design phase can be made error-free although not all details are present, yet.
Delegation
The delegation artefact can be used to delegate a requirement to a subsystem. As of this moment, the respective subsystem is responsible for satisfying the requirement. In the subsystem, the requirement becomes a so-called inherited requirement, since it was delegated to this subsystem by the parent system. A requirement can also be delegated to an atom in the same system, immediately satisfying the requirement. Furthermore, requirements can be delegated to one or several other requirement(s) (translation or splitting of a requirement) and several requirements can be delegated to one new requirement (joining of requirements). These constructs are typically used to make the contents of a requirement more specific when a requirement cannot be implemented in one subsystem or in one atom or less specific when multiple requirements are to be implemented by the same artefact. A simple delegation of a requirement to a system and then to an atom is visualized in Figure 2. The arrows in the Figure represent the requirement's trace.
Figure 2: A requirement is delegated to a subsystem first and implemented by an atom.
Additional repository elements
The following elements are used to give a Forest repository more functionality. More details on the elements can be found in the author's thesis. First, the extends artefact can be used for reusing a set of requirements, design, or implementation artefacts of an abstract system. The implements artefact can be used by an atom to explicitly satisfy a requirement. Furthermore, the delegation artefact relies on one or more source and one or more target artefacts to actually realize a relation. Finally, requirements, systems and atoms can use title, description, and motivation artefacts. The first one consists of a single line of text, whereas the latter two consist of rich text and can optionally contain one or more image artefacts.
Website last updated: July 11, 2007