Zum Hauptinhalt springen

Richtlinie: BPMN-Links auf Docs-Seiten

Verbindliche Entscheidung zur Linkkonvention​

Für site/static/bpmn/ml-process.bpmn gilt verbindlich:

  • Es werden ausschliesslich absolute Docs-Routen im Format /docs/<slug> verwendet.
  • Relative Slug-Referenzen wie orchestration-prefect/scheduling, ../... oder nur <slug> sind nicht erlaubt.
  • Der <slug>-Teil wird aus dem Frontmatter slug der Zielseite abgeleitet (Beispiel: slug: /orchestration-prefect/scheduling ⇒ BPMN-Link /docs/orchestration-prefect/scheduling).

Damit bleiben Links stabil, auch wenn sich die physische Dateistruktur unter site/docs/** verändert.

Konvention für Seiten mit Frontmatter-slug​

Jede Seite, die aus BPMN verlinkt wird, braucht ein explizites Frontmatter-slug:

---
slug: /<domain>/<page>
---

Korrekte Beispiele​

  • Seite mit slug: /orchestration-prefect/scheduling ⇒ BPMN: /docs/orchestration-prefect/scheduling
  • Seite mit slug: /data/feature-store ⇒ BPMN: /docs/data/feature-store
  • Seite mit slug: /observability/monitoring ⇒ BPMN: /docs/observability/monitoring

Nicht erlaubt​

  • orchestration-prefect/scheduling (kein /docs/-Präfix)
  • /orchestration-prefect/scheduling (ohne /docs/-Präfix in BPMN)
  • ../docs/orchestration-prefect/scheduling (relative Referenz)

Fallback für bewusst nicht verlinkbare Knoten​

Für technische Hilfsknoten oder reine Steuer-/Triggerknoten ohne eigene Docs-Seite ist der folgende Fallback verpflichtend:

<bpmn:documentation>NO_DOC_LINK: <kurzer Grund></bpmn:documentation>

Regeln:

  • NO_DOC_LINK: muss immer einen kurzen, verständlichen Grund enthalten.
  • Freitext ohne Präfix ist nicht zulässig.
  • Sobald eine fachliche Seite existiert, muss der Fallback durch einen /docs/<slug>-Link ersetzt werden.

Mapping: site/static/bpmn/ml-process.bpmn​

BPMN-Link (<bpmn:documentation>)Zielseite (Datei)
/docs/orchestration-prefect/schedulingsite/docs/03-orchestration-prefect/scheduling.mdx (u. a. StartEvent_Timer)
/docs/orchestration-prefect/incident-managementsite/docs/03-orchestration-prefect/incident-management.md
/docs/research-risk/manual-data-reviewsite/docs/05-research-risk/manual-data-review.md
/docs/data-catalog-openmetadata/purposesite/docs/01-data-catalog-openmetadata/purpose.mdx
/docs/data-catalog-openmetadata/ingestionsite/docs/01-data-catalog-openmetadata/ingestion.mdx
/docs/data-catalog-openmetadata/data-qualitysite/docs/01-data-catalog-openmetadata/data-quality.mdx
/docs/data/quarantinesite/docs/02-data/quarantine.md
/docs/orchestration-prefect/flowssite/docs/03-orchestration-prefect/flows.mdx
/docs/research-risk/portfolio-constructionsite/docs/05-research-risk/portfolio-construction.md
/docs/research-risk/approval-processsite/docs/05-research-risk/approval-process.md
/docs/observability/monitoringsite/docs/08-observability/monitoring.md
/docs/consumption/publish-dashboardsite/docs/07-consumption/publish-dashboard.md
/docs/data/feature-storesite/docs/02-data/feature-store.md
/docs/observability/decision-loggingsite/docs/08-observability/decision-logging.md
/docs/serving/deploymentsite/docs/06-serving/deployment.md
/docs/serving/scoringsite/docs/06-serving/scoring.md
/docs/research-risk/backtestingsite/docs/05-research-risk/backtesting.mdx
/docs/data/label-constructionsite/docs/02-data/label-construction.mdx
/docs/ml-lifecycle-mlflow/experimentssite/docs/04-ml-lifecycle-mlflow/experiments.mdx

Zusätzliche Drilldown-Assets​

  • site/static/bpmn/scheduling-detail.bpmn: Drilldown-Kontext für die Seite /docs/orchestration-prefect/scheduling.

Statischer Prüfschritt (CI)​

Der statische Check läuft über site/scripts/check-doc-links.mjs und ist in CI via .github/workflows/link-check.yml eingebunden.

Geprüft wird für ml-process.bpmn:

  1. Jeder <bpmn:documentation>-Eintrag ist entweder
    • ein gültiger /docs/<slug>-Link auf eine existierende Seite mit Frontmatter-slug, oder
    • ein gültiger NO_DOC_LINK: <grund>-Fallback.
  2. Ungültige Freitexte oder nicht auflösbare /docs/...-Routen lassen den Check fehlschlagen.

Pflege-Check bei Änderungen​

  1. In ml-process.bpmn nur /docs/<slug> oder NO_DOC_LINK: <grund> eintragen.
  2. Bei neuen /docs/...-Links prüfen, ob die Zielseite ein passendes Frontmatter-slug hat.
  3. pnpm run link-check lokal ausführen.
  4. Änderungen an BPMN-Knoten zusätzlich in der Traceability Matrix prüfen/aktualisieren.