spec: Add content from engineering manual

4 files changed, 27 insertions, 4 deletions

diff --git a/spec/spec/interface.yml b/spec/spec/interface.yml
index 95b6a3cb..f9616cff 100644
--- a/spec/spec/interface.yml
+++ b/spec/spec/interface.yml
@@ -20,6 +20,11 @@ spec-info:
         spec-type: name
     description: |
       This set of attributes specifies an interface specification item.
+      Interface items shall specify the interface of the software product to
+      other software products and the hardware.  Use
+      ${interface-domain:/spec-name} items to specify interface domains, for
+      example the ${/glos/term/api:/term}, C language, compiler, interfaces to
+      the implementation, and the hardware.
     required-attributes: all
 spec-name: Interface Item Type
 spec-type: interface
diff --git a/spec/spec/link.yml b/spec/spec/link.yml
index bd6aff8d..d8378064 100644
--- a/spec/spec/link.yml
+++ b/spec/spec/link.yml
@@ -20,7 +20,8 @@ spec-info:
         spec-type: uid
     description: |
       This set of attributes specifies a link from one specification item to
-      another specification item.
+      another specification item.  The links in a list are ordered.  The first
+      link in the list is processed first.
     required-attributes: all
 spec-name: Link
 spec-type: link
diff --git a/spec/spec/requirement-validation.yml b/spec/spec/requirement-validation.yml
index 453d6ca0..6b5fc07d 100644
--- a/spec/spec/requirement-validation.yml
+++ b/spec/spec/requirement-validation.yml
@@ -24,7 +24,8 @@ spec-info:
           method:
 
           * *By analysis*: A statement shall be provided how the requirement is
-            met, by analysing static properties of the software product.
+            met, by analysing static properties of the
+            ${/glos/term/softwareproduct:/term}.
 
           * *By inspection*: A statement shall be provided how the requirement
             is met, by inspection of the ${/glos/term/sourcecode:/term}.
diff --git a/spec/spec/root.yml b/spec/spec/root.yml
index 42bca776..12b4a729 100644
--- a/spec/spec/root.yml
+++ b/spec/spec/root.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
 enabled-by: true
 links: []
 spec-description: null
@@ -25,9 +25,25 @@ spec-info:
         spec-type: links
       type:
         description: |
-          It shall be the item type.
+          It shall be the item type.  The selection of types and the level of
+          detail depends on a particular standard and product model.  We need
+          enough flexibility to be in line with ECSS-E-ST-10-06 and possible
+          future applications of other standards.  The item type may be refined
+          further with additional type-specific subtypes.
         spec-type: name
     description: |
+      The technical specification of RTEMS will contain for example
+      requirements, specializations of requirements, interface specifications,
+      test suites, test cases, and requirement validations.  These things will
+      be called *specification items* or just *items* if it is clear from the
+      context.
+
+      The specification items are stored in files in ${/glos/term/yaml:/term}
+      format with a defined set of key-value pairs called attributes.  Each
+      attribute key name shall be a :ref:`SpecTypeName`.  In particular, key
+      names which begin with an underscore (``_``) are reserved for internal
+      use in tools.
+
       This is the root specification item type.
     required-attributes: all
 spec-name: Root Item Type