#1 added mermaid support plus content for concept and use case

.github/workflows/create-pdf.yml → .github/workflows/build.yml

@@ -1,4 +1,4 @@
-name: Create PDF
+name: Build Website
 
 on:
   push:

Makefile

@@ -69,6 +69,7 @@ endif
 	pip install --upgrade mkdocs-include-markdown-plugin
 	pip install --upgrade mkdocs-awesome-pages-plugin
 	pip install --upgrade mkdocs-macros-plugin
+	pip install --upgrade mkdocs-mermaid2-plugin
 	pip install --upgrade mdx-spanner
 	pip install --upgrade markdown-emdash
 

docs/.pages.yaml

@@ -1,4 +1,5 @@
 nav:
   - index.md
   - objective
+  - concept
   - product

docs/concept/.pages.yaml

@@ -0,0 +1,7 @@
+title: Use Case Tree Concepts
+nav:
+  - use-case.md
+  - persona.md
+  - story.md
+  - concept.md
+  - ...

docs/concept/concept.md

@@ -17,7 +17,7 @@ classDiagram
         - vocabulary: Vocabulary
         - stories: Story[]
     }
-    link UseCase "http://localhost:8000/concept/use-case/"
+    link UseCase "../use-case/"
     UseCase --> UseCase : requires
     Vocabulary "*" --> "*" Concept
     Vocabulary "*" --> "*" Term

docs/concept/dataset.md

@@ -1,3 +1,4 @@
-# Input Concept
+# Dataset
+
 
 

docs/concept/outcome.md

@@ -1,3 +1,4 @@
-# Concept
+# Outcome
+
 
 

docs/concept/persona.md

@@ -1 +1,2 @@
-# Use Case
+# Persona
+

docs/concept/story.md

@@ -1,3 +1,3 @@
-# Input Concept
+# Story
 
 

docs/concept/use-case.md

@@ -0,0 +1,78 @@
+# Use Case
+
+A Use Case specifies a distinct set of business requirements --- captured
+as an "executable model" --- resulting in a specific business outcome.
+
+## Life cycle
+
+Use Cases go through a life-cycle of continuous improvement such as:[^1]
+
+```mermaid
+journey
+    title Use Case Life Cycle
+    section Plan
+        Discovery: 5: Business, Analyst
+        Negotiation: 2: Business, Owner, Analyst
+        Agreed: 5: Business, Owner
+    section Build
+        Implementation: 1: Analyst, Ontologist, Engineer
+        Acceptance Test: 3: Owner
+        Delivered: 4: Engineer
+    section Run
+        Deployed: 5: DevOps
+        Decommissioned: 1: DevOps
+```
+
+[^1]: the life-cycle diagram shown is obviously a simplification
+
+## Key components
+
+For every Use Case we specify:
+
+- A name and a description
+- The desired or expected business outcome(s) and how they can be measured
+- The ["personas"](persona.md) of all the people and systems that are involved
+  in the domain or scope represented by the Use Case
+- The concepts and their terms as they're used in the context of the Use Case
+
+At a later stage in the life-cycle of the Use Case we add:
+
+- The stories, see [Story](story.md)
+- The datasets and their ontologies
+- The workflows
+
+Specialists of various disciplines in the organization can add their details
+such as:
+
+- detailed business rationale, tied to the before-mentioned business outcomes
+- milestones, versions, projects, timelines, roadmaps, budgets
+- issues, tickets
+- environment topologies, deployments and configurations
+- detailed information about the various types of dependencies
+
+## Tech Audience
+
+The term "use case" means something specific to a technical audience who
+usually assume that the term use case means what the Object Management Group (OMG)
+defines what it is in their Unified Modeling Language (UML) and
+its ["use case diagrams"](https://en.wikipedia.org/wiki/Use_case_diagram).
+
+Although there are many similarities and overlap --- which is why we are repurposing
+the term --- it is not exactly the same, in our Use Case Tree Method:
+
+- use cases often are used a much broader and more abstract container concept ---
+  compared to a UML Use Case --- that can be put in a "tree structure" where at the
+  highest levels of these trees a use case can represent a capability domain or 
+  a "strategic use case" --- or basically anything that fits well with the business.
+- at the lowest levels in this tree we would end up with use cases that are much more
+  like turn-key components for the EKG, 100% reusable delivering "no code"-functionality[^1].
+
+[^1]: [No-code](https://en.wikipedia.org/wiki/No-code_development_platform) or 
+      [Low-code](https://en.wikipedia.org/wiki/Low-code_development_platform) development
+      allows non-programmers to create applications without
+      hard-wiring business logic with a programming language
+
+
+
+
+

docs/extra/refresh_on_toggle_dark_light.js

@@ -0,0 +1,10 @@
+var paletteSwitcher1 = document.getElementById("__palette_1");
+var paletteSwitcher2 = document.getElementById("__palette_2");
+
+paletteSwitcher1.addEventListener("change", function () {
+    location.reload();
+});
+
+paletteSwitcher2.addEventListener("change", function () {
+    location.reload();
+});

mkdocs.yml

@@ -21,11 +21,15 @@ theme:
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default
+      primary: indigo
+      accent: light-blue
       toggle:
         icon: material/toggle-switch-off-outline
         name: Switch to dark mode
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
+      primary: indigo
+      accent: deep orange
       toggle:
         icon: material/toggle-switch
         name: Switch to light mode
@@ -53,12 +57,24 @@ extra:
       link: https://www.linkedin.com/company/EKGF
     - icon: fontawesome/brands/github
       link: https://github.com/EKGF/use-case-tree-method
+extra_javascript:
+  - https://unpkg.com/mermaid/dist/mermaid.min.js
+  - extra/refresh_on_toggle_dark_light.js
 plugins:
   - include-markdown
   - search:
       prebuild_index: true
       lang:
         - en
+  - mermaid2:
+      arguments:
+        # test if its __palette_1 (dark) or __palette_2 (light)
+        # for mkdocs-material >=8.0.0
+        theme: |
+          ^(JSON.parse(__md_get("__palette").index == 1)) ? 'dark' : 'light'
+#        theme: |
+#          ^(window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'
+        securityLevel: 'loose'
   - awesome-pages:
       filename: .pages.yaml
       collapse_single_pages: false
@@ -77,13 +93,16 @@ markdown_extensions:
   - footnotes
   - tables
   - md_in_html
-  - pymdownx.highlight:
-      anchor_linenums: true
   - pymdownx.inlinehilite
   - pymdownx.snippets:
       check_paths: true
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      # make exceptions to highlighting of code:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:mermaid2.fence_mermaid
   - pymdownx.tabbed:
       alternate_style: true
   - pymdownx.tasklist: