Revamp workflow guide

.github/workflows/build-guides.yml

@@ -2,42 +2,84 @@ name: Build Guides
 
 on:
   push:
-    branches-ignore: [ 'temp/*' ]
+    branches-ignore:
+      - 'temp/*'
+    tags:
+      - '*'
   pull_request:
-    branches: [ main ]
+    branches:
+      - 'main'
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
 
 jobs:
-  build-guides:
-    name: Build SSP Traceability Guides
+
+  generate-html:
+    runs-on: ubuntu-24.04
+    steps:
 
-    runs-on: ubuntu-22.04
+    - name: Checkout
+      uses: actions/checkout@v6
+      with:
+        submodules: recursive
 
-    steps:
-    - name: checkout
-      uses: actions/checkout@v4
-    - name: prepare
-      run: mkdir build && mkdir build/workflow-guide 
-    - name: build workflow guide
+    - name: Generate revnumber
+      run: |
+        [[ $GITHUB_REF_TYPE == "tag" ]] && REVNUMBER=${GITHUB_REF:11} || REVNUMBER=${GITHUB_SHA:0:7}
+        echo GITHUB_SHA:      $GITHUB_SHA
+        echo GITHUB_REF_TYPE: $GITHUB_REF_TYPE
+        echo GITHUB_REF:      $GITHUB_REF
+        echo REVNUMBER:       $REVNUMBER
+        echo "REVNUMBER=$REVNUMBER" >> $GITHUB_ENV
+
+    - name: Create build directory
+      run: |
+        mkdir -p build/workflow-guide/images
+
+    - name: Generate HTML
       uses: avattathil/asciidoctor-action@master
       with:
-        program: "asciidoctor -D build/workflow-guide --backend=html5 --attribute=revnumber=${GITHUB_REF#refs/heads/}-$GITHUB_SHA --attribute=revdate=$(date +%F) workflow-guide/index.adoc"
-    - name: copy images
-      run: tar cf - workflow-guide/images | tar xfC - build
-    - name: archive workflow guide
-      uses: actions/upload-artifact@v4
+        program: "asciidoctor --base-dir workflow-guide --destination-dir=../build/workflow-guide --backend=html5 --attribute=revnumber=${{ env.REVNUMBER }} --attribute=revdate=$(date +%F) workflow-guide/index.adoc"
+
+    - name: Copy resources
+      run: |
+        cp workflow-guide/images/* build/workflow-guide/images
+
+    - name: Create ZIP archive
+      uses: actions/upload-artifact@v6
       with:
         name: Workflow-Guide
         path: build/workflow-guide/*
         if-no-files-found: error
-    - name: extract branch name
+
+    - name: Extract branch name
       id: extract_branch
       shell: bash
-      run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"
-    - name: deploy
+      run: echo "branch=$(echo ${GITHUB_REF#refs/heads/})" >> $GITHUB_OUTPUT
+
+    - name: Move to published directory
       if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-      uses: peaceiris/actions-gh-pages@v3.7.0-8
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: build
-        destination_dir: ${{ steps.extract_branch.outputs.branch }}
-        enable_jekyll: true
+      shell: bash
+      run: mkdir _site && mv build _site/${{ steps.extract_branch.outputs.branch }}
+
+    - name: Upload Pages artifact
+      if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+      uses: actions/upload-pages-artifact@v4
+
+  publish-html:
+    needs: generate-html
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-24.04
+    steps:
+
+    - name: Deploy to Github Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

workflow-guide/0___preamble.adoc

@@ -1,4 +1,4 @@
-The SSP Traceability Workflow Guide is a supplementary documentation to the SSP Traceability Specification 1.0. While the SSP Traceability Specification 1.0 essentially describes a data format for STMD files in the sense of a normative document, the SSP Traceability Workflow Guide addresses how and in which way  Glue Paerticles are used in industrial practice. It thus addresses topics and answers questions that the SSP Traceability Specification 1.0 as a normative document cannot address and answer.
+The SSP Traceability Workflow Guide is a supplementary documentation to the SSP Traceability Specification 1.0. While the SSP Traceability Specification 1.0 essentially describes a data format for STMD files in the sense of a normative document, the SSP Traceability Workflow Guide addresses how and in which way the SSP Traceability can be used in industrial practice. It thus addresses topics and answers questions that the SSP Traceability Specification 1.0 as a normative document cannot address and answer.
 
 This is a development version of the SSP Traceability Workflow Guide.
 https://github.com/PMSFIT/SSPTraceabilityGuides/releases[Releases] and https://github.com/PMSFIT/SSPTraceabilityGuides/issues[issues] can be found on https://github.com/PMSFIT/SSPTraceabilityGuides[github.com/PMSFIT/SSPTraceabilityGuides].

workflow-guide/1___introduction.adoc

@@ -1,79 +1,8 @@
 == Introduction
 
-Based on typical scenarios in the simulation of complex systems, the SSP Traceability Workflow Guide intends to show how simulation processes and model creation processes may be documented using the Glue Particle approach. A Glue Particle is an XML file in which all simulation or model creation relevant resources and information are described or linked. The goals of the glue particle approach are:
+=== Purpose and structure of the user guide
 
-* Traceable documentation of simulation and modeling processes for retrospective analyses
-
-* Replacement of order-relevant information and resources for simulation and modeling processes in cross-company collaboration
-
-* Transfer of simulation or modeling process relevant information and resources within the company between departments or IT tools
-
-* Reuse of simulation-relevant resources and informtion (e.g., models, parameters, tools, etc.) for simulation repetition
-
-* Reuse resources such as simulation models or parameters for similar simulations.
-
-#Align these gpals with the scenarios in chapter <<SSP collaboration and traceability scenarios>>#
-
-
-
-
-
-The SSP Traceability Workflow Guide intends to provide support on how to handle Glue Particles with the focus on workflows and processes in industrial practice. In industrial practice topics come into focus that go beyond the scope of a data format specification, including the topics in the following list.
-
-- Consistency and quality assurance
-
-- Glue Particle data management
-
-- Dealing with complex multi Glue Particle constellations
-
-- Retrospective interpretation of Glue Particles
-
-- Reuse of Glue Particles
-
-- Exchange of Glue Particles between IT tools and systems
-
-- Cross-company exchange of Glue Particles
-
-- and many more
-
-This is where the SSP Traceability Workfkow Guide comes in. The Workflow Guide addresses these issues and provides recommendations for handling Glue Particles in industrial practice.
-
-=== Definition of esential term
-
-In the context of the development of the SSP Traceability Standrd, the terms scenarios, workflow, process and use case are frequently used. These terms will be explained and distinguished from each other but also positioned in relation to each other.
-
-*Scenario*
-
-A scenario describes the situation from a business perspective in which Glue Particles may be used and offer or generate significant added value. The description of a scenario includes the naming of the organization or roles involved as well as the business goals of the organization or roles involved.
-
-The term scenario in this context should not be confused with the term scenario as used in the context of automated and autonomous driving. In automated and autonomous driving, a scenario refers to a complex traffic situation with a number of moving and non-moving objects in the road space and a complex constellation of many boundary conditions in which an automated or autonomous vehicle is to move.
-
-*Workflow*
-
-The workflow describes how Glue Particle will be used in each scenario and how they may provide and generate the expected added value. The process flow of each scenario is described by at least one, or if necessary, by several alternative or complementary workflows. Essentially, process diagrams and additional textual descriptions are used. Here, the focus is on the process-related handling of the Glue Particle
-
-*Use case*
-
-A use case describes how the Glue Particle is handled in very specific, narrowly defined situations, or how it is interacted with manually or technically. The main question here is who does what with the Glue Particle and when, and what the respective result of the interaction is. The focus here is on the operational handling of the glue particle.
-
-*Process*
-
-The term process may be used on different levels and means that interrelated activities, interactions and communications have a certain causal and temporal sequence. In addition, the term may also be part of fixed and thus predetermined terms, such as commissioning process, requirements process or export process. The term process may therefore appear in this documentation in the context of scenarios as well as in the context of workflows and use cases.
-
-
-
-=== Conventions used in this document
-
-* The version number of this documentation is to be interpreted according to the _Semantic Versioning Specification (SemVer) 2.0.0_ <<SEMVER200>>.
-
-* The key words *MUST*, *MUST NOT*, *REQUIRED*, *SHALL*, *SHALL NOT*, *SHOULD*, *SHOULD NOT*, *RECOMMENDED*, *NOT RECOMMENDED*, *MAY*, and *OPTIONAL* in this document are to be interpreted as described in _RFC 2119_ <<RFC2119>>.
-
-=== Document structure
-
-#Hier zum Schluss noch die Dokumentstruktur einführen#
-
-##
-* Glue Particle Approach
-* Szenarien und Workflows
-* Use Cases für GP Handlig
-##
+The user guide is intended to provide information and examples of how the SSP Layered Standard Traceability can be applied.
+It is important to note that the Layered Standard SSP Traceability is in XML format, which is clearly structured and readable, but should be created and modified using appropriate tool support.
+This is comparable to the use of FMUs or SSP.
+Further introductory information is described in chapters 1-3 of the SSP LS Traceability <<SSPLST>>.