Conformance example1 preliminary SEBoK structure and EU CRA statements

conformance/example1/README.md

@@ -24,6 +24,56 @@ data (digital and physical identifiers) and packaging the product:
   - Model
   - Serial Number
 
+## Demonstrated System Engineering Process and Tools
+
+### System Engineering Body of Knowledge (SEBoK)
+
+This example is attempting to follow the best practices described in the
+[Guide to the Systems Engineering Body of Knowledge (SEBoK)](https://sebokwiki.org/wiki/Guide_to_the_Systems_Engineering_Body_of_Knowledge_(SEBoK)).
+
+The SEBoK Wiki Glossary quotes the following definition for the
+[Vee (V) Model](https://sebokwiki.org/wiki/Vee_(V)_Model_(glossary)):
+
+> The technical aspect of the project cycle is envisioned as a "Vee", starting with User needs on the upper left and ending with a User-validated system on the upper right. (Forsberg and Mooz 1991)
+
+The SEBoK considers Users to be a subset of the set of Stakeholders.
+This results in approximately the following Vee Model:
+
+```
+  Stakeholder Needs
+        ^
+        \  Stakeholder Requirements <-- proven met by -- System Validations
+         \   (solution constraints)                    ^
+          \                                           /
+  +--> System Requirements <--- verified by ---- System Verifications
+  | repeat  ^                                       ^
+  | until    \  System Architecture                 /
+  | directly  \  decomposes System into            /
+  | implement  \                                  /
+  +--------- SysElement Requirements <------ sysElement Verification
+```
+
+Each resulting SysElement then is treated as a new System-of-interest (SOI)
+and is further decomposed until it is small enough to be directly implemented
+and verified.
+
+
+### International Council on System Engineering (INCOSE)
+
+This example also attempts to write requirements following the
+[International Council on Systems Engineering](https://www.incose.org/) recommendations. 
+A soft copy of their [Guide to Writing Requirements Summary Sheet](https://portal.incose.org/commerce/store?productId=commerce-merchandise%23INCOSE-GUIDEWRITINGREQSUM)
+may be purchased from the INCOSE store by non-members for $0.00 (zero).
+
+The example content is initially being captured using the open-source
+tool [StrictDoc](https://github.com/strictdoc-project/strictdoc),
+which is a FOSS software tool for technical documentation and requirements management.
+StrictDoc has been successfully used for technical documentation certified by
+the European Space Agency. It supports the following features key to this example:
+- document creators can specify their own document node types,
+- node relationship directions and trace analysis,
+- support for generating graphs from editable textual graph descriptions (Mermaid UML)
+
 
 ## Comments
 

conformance/example1/content/src/.gitignore

@@ -0,0 +1 @@
+__pycache__

conformance/example1/content/src/SOI/SAMPLE/interface_requirements/sdoc/index.sdoc

@@ -0,0 +1,26 @@
+[DOCUMENT]
+MID: 43b3bf7d570d4089b3cd76a4c765cd62
+TITLE: Interface Requirements
+OPTIONS:
+  ENABLE_MID: True
+
+[GRAMMAR]
+IMPORT_FROM_FILE: @sample_interface_requirements_grammar
+
+[TEXT]
+MID: 9be29edda6c5401fbb2a05ff71cd0fd0
+STATEMENT: >>>
+SPDX-License-Identifier: Apache-2.0
+<<<
+
+[TEXT]
+MID: 1d78c62fa24740e49fd245550e11dd13
+STATEMENT: >>>
+From `SEBoK Wiki Glossary - interface <https://sebokwiki.org/wiki/Interface_(glossary)>`_:
+
+- A shared boundary between two functional units, defined by various characteristics pertaining to the functions, physical signal exchanges, and other characteristics. (ISO/IEC 1993)
+
+- A hardware or software component that connects two or more other components for the purpose of passing information from one to the other. (ISO/IEC 1993)
+
+- To connect two or more components for the purpose of passing information from one to the other. (ISO/IEC/IEEE 2009)
+<<<

conformance/example1/content/src/SOI/SAMPLE/sdoc/index.sdoc

@@ -0,0 +1,51 @@
+[DOCUMENT]
+TITLE: SAMPLE
+
+[TEXT]
+STATEMENT: >>>
+SPDX-License-Identifier: Apache-2.0
+<<<
+
+[TEXT]
+STATEMENT: >>>
+The System-of-Interest named SAMPLE is the top-level system in this example. 
+
+It is expected to be composed of the following subsystems:
+
+.. raw:: html
+
+    <pre class="mermaid">
+    ---
+    title: Topology of Systems-of-Interest
+    ---
+    stateDiagram-v2
+
+        state SAMPLE {
+            TBD_Security_Vulnerability_Reporting: TBD <br/> Security <br/> Vulnerability <br/> Reporting <br/> Server
+            TBD_Desktop_SW: TBD <br/> Desktop SW
+            TBD_Mobile_SW: TBD <br/> Mobile SW
+            TBD_Devices: TBD <br/> Device(s)
+            TBD_Cloud_SW: TBD <br/> Cloud SW
+            TBD_Digital_Component_Update_Server: TBD <br/> Digital <br/> Component <br/> Update <br/> Server
+        }
+
+    </pre>
+<<<
+
+[DOCUMENT_FROM_FILE]
+FILE: ../system_requirements/sdoc/index.sdoc
+
+[DOCUMENT_FROM_FILE]
+FILE: ../system_verifications/sdoc/index.sdoc
+
+[DOCUMENT_FROM_FILE]
+FILE: ../system_architectures/sdoc/index.sdoc
+
+[DOCUMENT_FROM_FILE]
+FILE: ../interface_requirements/sdoc/index.sdoc
+
+[DOCUMENT_FROM_FILE]
+FILE: ../system_element_requirements/sdoc/index.sdoc
+
+[DOCUMENT_FROM_FILE]
+FILE: ../system_element_verifications/sdoc/index.sdoc

conformance/example1/content/src/SOI/SAMPLE/system_architectures/sdoc/index.sdoc

@@ -0,0 +1,187 @@
+[DOCUMENT]
+MID: af66c5de119447b58b950dd710d34b8a
+TITLE: System Architecture(s)
+OPTIONS:
+  ENABLE_MID: True
+
+[GRAMMAR]
+IMPORT_FROM_FILE: @sample_system_architectures_grammar
+
+[TEXT]
+MID: 84713f51e27b4ea4bc3242a8e2f1fba7
+STATEMENT: >>>
+SPDX-License-Identifier: Apache-2.0
+<<<
+
+[TEXT]
+MID: 0f68a238be874bdcb25a5fbb9f9bcb5c
+STATEMENT: >>>
+From `SEBoK Wiki Glossary - Architecture <https://sebokwiki.org/wiki/Architecture_(glossary)>`_:
+
+- fundamental concepts or properties of a system in its environment embodied in its elements, relationships, and in the principles of its design and evolution (ISO/IEC/IEEE 2015, Section 4.5)
+
+- The organizational structure of a system or component; the organizational structure of a system and its implementation guidelines. (ISO/IEC 2009, 1)
+
+- Fundamental concepts or properties of a system in its environment embodied in its elements, relationships, and in the principles of its design and evolution. (ISO/IEC 2011, section 3.2)
+<<<
+
+[[SECTION]]
+MID: 8ecb476dee204236beaca929246ca738
+TITLE: Architecture Decision Timeline
+
+[[/SECTION]]
+
+[[SECTION]]
+MID: 36617eaf332a4efda48b7b596c66e413
+TITLE: Architecture Decisions
+
+[[/SECTION]]
+
+[[SECTION]]
+MID: e5076a1d1494497e88e7df3bc0dea09a
+TITLE: Logical View
+
+[TEXT]
+MID: 671e4f76645344f1b0b35ee9f60b75bb
+STATEMENT: >>>
+From `4+1 Architectural View Model <https://en.wikipedia.org/wiki/4%2B1_architectural_view_model>`_:
+
+  The logical view is concerned with the functionality that the system provides to end-users. UML diagrams are used to represent the logical view, and include class diagrams, and state diagrams. (Mikko Kontio (2008, July) Architectural manifesto: Designing software architectures, Part 5)
+<<<
+
+[TEXT]
+MID: d5312fdaf0de42658b9d2287c3eea317
+STATEMENT: >>>
+.. raw:: html
+
+    <pre class="mermaid">
+    ---
+    title: Example UML State Diagram
+    ---
+    stateDiagram-v2
+
+        productMfg: Product Manufacturer
+        productMfgWebsite: Product Mfg. Website
+        productMfgSupport: Product Mfg. Customer Support
+        productSecurityReporting: Product Mfg. <br/> Security Reporting
+
+        state productMfg {
+            direction LR
+
+            productMfgWebsite
+            productMfgSupport
+            productSecurityReporting
+        }
+
+        Customer
+
+        Product
+
+    </pre>
+<<<
+
+[[/SECTION]]
+
+[[SECTION]]
+MID: 2f6357676b7148049baec8001b7d464b
+TITLE: Physical View
+
+[TEXT]
+MID: 7949001aaf3a413797d5022c40669144
+STATEMENT: >>>
+From `4+1 Architectural View Model <https://en.wikipedia.org/wiki/4%2B1_architectural_view_model>`_:
+
+  The physical view (aka the deployment view) depicts the system from a system engineer's point of view. It is concerned with the topology of software components on the physical layer as well as the physical connections between these components. UML diagrams used to represent the physical view include the deployment diagram. (Mikko Kontio (2008, July) Architectural manifesto: Designing software architectures, Part 5)
+<<<
+
+[TEXT]
+MID: 85c0235670da4549884201f91ff364a0
+STATEMENT: >>>
+.. raw:: html
+
+    <pre class="mermaid">
+    ---
+    title: Example UML Entity Relationship
+    ---
+    erDiagram
+        CUSTOMER ||--o{ ORDER : places
+        ORDER ||--|{ LINE-ITEM : contains
+        CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+
+    </pre>
+<<<
+
+[[/SECTION]]
+
+[[SECTION]]
+MID: 2fe14357b35b4f0aa9b184fdb1abe15c
+TITLE: Concurrency (Process) View
+
+[TEXT]
+MID: 5d6d15025b8d486a8aabf215fdf7e40b
+STATEMENT: >>>
+From `4+1 Architectural View Model <https://en.wikipedia.org/wiki/4%2B1_architectural_view_model>`_:
+
+  The process view deals with the dynamic aspects of the system, explains the system processes and how they communicate, and focuses on the run time behavior of the system. The process view addresses concurrency, distribution, integrator, performance, and scalability, etc. UML diagrams to represent process view include the sequence diagram, communication diagram, activity diagram. (Hui, LM; Leung, CW; Fan, CK; Wong, TN (2004). "Modelling agent-based systems with UML". Proceedings of the Fifth Asia Pacific Industrial Engineering and Management Systems Conference.), (Mikko Kontio (2008, July) Architectural manifesto: Designing software architectures, Part 5)
+<<<
+
+[[/SECTION]]
+
+[[SECTION]]
+MID: 06283fdaa2da401788553f0cdfa4cbd3
+TITLE: Development View
+
+[TEXT]
+MID: 652c07a9ceb0481f8819db9c28251c0e
+STATEMENT: >>>
+From `4+1 Architectural View Model <https://en.wikipedia.org/wiki/4%2B1_architectural_view_model>`_:
+
+  The development view (aka the implementation view) illustrates a system from a programmer's perspective and is concerned with software management. UML Diagrams used to represent the development view include the Package diagram and the Component diagram. (Mikko Kontio (2008, July) Architectural manifesto: Designing software architectures, Part 5)
+<<<
+
+[[/SECTION]]
+
+[[SECTION]]
+MID: 29a05dd3c9504eb1a78b28a8e1cfc71d
+TITLE: Scenarios
+
+[TEXT]
+MID: 63b5a1579fa944dc8456deaf2e1d4405
+STATEMENT: >>>
+From `4+1 Architectural View Model <https://en.wikipedia.org/wiki/4%2B1_architectural_view_model>`_:
+
+  The description of an architecture is illustrated using a small set of use cases, or scenarios, which become a fifth view. The scenarios describe sequences of interactions between objects and between processes. They are used to identify architectural elements and to illustrate and validate the architecture design. They also serve as a starting point for tests of an architecture prototype. This view is also known as the use case view.
+<<<
+
+[TEXT]
+MID: e0dab2b7af414a92855ef3613ccba1b1
+STATEMENT: >>>
+.. raw:: html
+
+    <pre class="mermaid">
+    ---
+    title Example UML Sequence Diagram
+    ---
+    sequenceDiagram
+
+      %% Set non-default presentation order of participants
+      participant A as Alice<br/>Johnson
+      participant J as John
+      participant C
+
+      C -->> A : Clock chimes
+
+      activate A
+      A ->> J : How are you?
+
+      activate J
+      note over J : John thinks for a moment
+
+      J ->> A : Fine
+      deactivate J
+      deactivate A
+
+    </pre>
+<<<
+
+[[/SECTION]]

conformance/example1/content/src/SOI/SAMPLE/system_element_requirements/sdoc/index.sdoc

@@ -0,0 +1,22 @@
+[DOCUMENT]
+MID: 9a5689a75c354b019acf55761ae02ca7
+TITLE: System Element Requirements
+OPTIONS:
+  ENABLE_MID: True
+
+[GRAMMAR]
+IMPORT_FROM_FILE: @sample_system_element_requirements_grammar
+
+[TEXT]
+MID: 2f9e70c900604e35a4a61961afb6e19b
+STATEMENT: >>>
+SPDX-License-Identifier: Apache-2.0
+<<<
+
+[TEXT]
+MID: 49ebfa8c1d414aa2aa66aff2153c2f13
+STATEMENT: >>>
+From `SEBoK Wiki Glossary - system element <https://sebokwiki.org/wiki/System_Element_(glossary)>`_:
+
+- A member of a set of elements that constitutes a system. A system element is a discrete part of a system that can be implemented to fulfill specified requirements. A system element can be hardware, software, data, humans, processes (e.g., processes for providing service to users), procedures (e.g., operator instructions), facilities, materials, and naturally occurring entities (e.g., water, organisms, minerals), or any combination. (ISO/IEC 15288:2015)
+<<<

conformance/example1/content/src/SOI/SAMPLE/system_element_verifications/sdoc/index.sdoc

@@ -0,0 +1,30 @@
+[DOCUMENT]
+MID: 97fadfb8f97a481a8205cf619c53f4f6
+TITLE: System Element Verifications
+OPTIONS:
+  ENABLE_MID: True
+
+[GRAMMAR]
+IMPORT_FROM_FILE: @sample_system_element_verifications_grammar
+
+[TEXT]
+MID: 715801b3dc784aefab88fe5afc443e3e
+STATEMENT: >>>
+SPDX-License-Identifier: Apache-2.0
+<<<
+
+[TEXT]
+MID: 849ea88ccbf040bcbce53b9c15dbf7f8
+STATEMENT: >>>
+From `SEBoK Wiki Glossary - verification <https://sebokwiki.org/wiki/Verification_(glossary)>`_:
+
+- Confirmation, through the provision of objective evidence, that specified (system) requirements have been fulfilled. (ISO/IEC 2008, section 4.38)
+
+- Verification is a set of activities that compares a system or system element against the required characteristics. This includes, but is not limited to, specified requirements, design description and the system itself. The system was built right. (ISO/IEC/IEEE 2015, 1, Section 6.4.6)
+
+- The evaluation of whether or not a product, service, or system complies with a regulation, requirement, specification, or imposed condition. It is often an internal process. Contrast with validation. (PMI 2013)
+
+- The process of evaluating a system or component to determine whether the products of a given development phase satisfy the conditions imposed at the start of that phase. (IEEE 1012-2004, 3.1.36)
+
+- Process of providing objective evidence that the software and its associated products comply with requirements for all life cycle activities during each life cycle process, satisfy standards, practices, and conventions during life cycle processes, and successfully complete each life cycle activity and satisfy all the criteria for initiating succeeding life cycle activities. (IEEE 829-2008, 3.1.54)
+<<<