#1 added plantuml support and used it for usecase and persona page

.github/workflows/build.yml

@@ -8,7 +8,7 @@ on:
       - '*'
 
 jobs:
-  website:
+  website-ubuntu:
     runs-on: ubuntu-latest
     steps:
       -
@@ -48,3 +48,35 @@ jobs:
         env:
           PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
         run: make --environment-overrides docs-deploy
+
+  website-macos:
+    runs-on: macos-latest
+    steps:
+      -
+        name: Set up Git repository
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+      -
+        uses: actions/cache@v2
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      -
+        name: Install all MkDocs dependencies
+        env:
+          PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
+        run: make --environment-overrides docs-install
+      -
+        name: Build Site
+        if: ${{ github.ref != 'refs/heads/main' }}
+        env:
+          PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
+        run: make --environment-overrides docs-build
+      -
+        name: Deploy Site
+        if: ${{ github.ref == 'refs/heads/main' }}
+        env:
+          PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
+        run: make --environment-overrides docs-deploy

.tool-versions

@@ -1,2 +1,3 @@
 python 3.10.2
 nodejs 17.4.0
+java openjdk-17

Makefile

@@ -58,6 +58,7 @@ docs-install-brew-packages: docs-install-brew
 	brew upgrade libjpeg || brew install libjpeg
 	brew upgrade libpng || brew install libpng
 	brew upgrade zlib || brew install zlib
+	brew upgrade plantuml || brew install plantuml
 
 .PHONY: docs-install-brew
 ifeq ($(YOUR_OS), Linux)
@@ -104,6 +105,8 @@ endif
 	@echo "Install packages via pip:"
 	pip install --upgrade pip
 	pip install --upgrade wheel
+#	pip install --upgrade plantuml-markdown
+	pip install --upgrade mkdocs-build-plantuml-plugin
 	pip install --upgrade mkdocs
 	pip install --upgrade mkdocs-localsearch
 	pip install --upgrade mkdocs-include-markdown-plugin

docs/concept/concept.md

@@ -17,7 +17,6 @@ classDiagram
         - vocabulary: Vocabulary
         - stories: Story[]
     }
-    link UseCase "../use-case/"
     UseCase --> UseCase : requires
     Vocabulary "*" --> "*" Concept
     Vocabulary "*" --> "*" Term
@@ -31,4 +30,9 @@ classDiagram
     Concept --> Concept : broader
     Concept --> Term : preferred
     UseCase --> "1" Vocabulary : use case vocabulary
+    Persona "1" --o "0..*" Story
+    link UseCase "../use-case/"
+    link Story "../story/"
+    link Concept "../concept/"
+    link Persona "../persona/"
 ```

docs/concept/persona.md

@@ -1,2 +1,51 @@
 # Persona
 
+=== "Business Audience"
+
+    For any given Use Case we need to have a list of all the different types of players.
+    In the initial stages of the life cycle of a use case it is less relevant whether these players
+    are called Stakeholders, Actors, Roles, User Types or Systems, we simply need to know what terms the
+    actual users, the real customer(s) of the use case, are using for them in their daily practice.
+
+    We call them Personas.
+
+    For example, in the use case "Legal Entity Management" you would have Personas like:
+
+    - Auditor
+    - Data Owner
+    - Shareholder
+    - Director
+    - Signator
+        - Signator Power Pursuent to Commercial Register
+    - Board Member
+    - Legal Council
+    - Liquidator
+    - ...
+
+    Many of these Personas are involved in multiple use cases and are grouped together in _persona taxonomies_
+    and defined in _ontologies_ with "machine readable meaning" that can be used to let algorithms "understand"
+    the actual context and act upon it.
+
+=== "Data & Tech Audience"
+
+    In traditional use case modelling people use the term _Actor_ rather than _Persona_.
+    The term _Actor_ is also used in a TOGAF Metamodel and combined with the term _Role_ whereby an actor 
+    assumes a role to perform a task.
+
+    The Use Case Tree Method does not make that distinction, primarily to keep things as simple as possible when
+    capturing requirements --- primarily as [stories](story.md) --- but also because the term Persona combines both
+    concepts into one whereby:
+
+    - Actors assuming a Role is fully automated, context dependent, model-, rule- and policy-driven
+    - Personas are [Concepts](concept.md) tied to Ontology-defined Classes that can inherit from other Persona types
+    - Personas are not just the "users" (or systems) of the use case but also any other party in the related
+      data-models (or EKG models/ontologies). For instance, your user can have the persona "Legal Entity Maintainer"
+      but since the legal entity can have a Director as well, the Director is also a Persona, even when that
+      Director might never be an active user of the system.
+
+
+=== "Model"
+
+A subset of the model, as a UML Class Diagram, around **Persona**.
+
+![Context](../diagrams/out/persona-class-diagram.svg#darkable)

docs/concept/use-case.md

@@ -3,27 +3,33 @@
 A Use Case specifies a distinct set of business requirements --- captured
 as an "executable model" --- resulting in a specific business outcome.
 
+## Process
+
+Ideas for use cases could come from any person in the organization at any point in time.
+We want all these ideas to end up in the organization's Use Case Tree, whether they are viable or not.
+If an idea for a given use case is rejected then show the rationale for that to everyone so that everyone can
+learn, and we're not wasting any time on that idea again. 
+
+Let people contribute. All knowledge workers, all specialist users, data architects, technical architects, ontologists,
+end users, business executives, literally anyone should be allowed to understand:
+
+- what's our business identity? Our mission and strategy?
+- how does that map to our current and future data and technology landscape?
+- (without becoming too technical or detailed, we want everyone to be able to chip in)
+- how does our "technical debt" fit in? (identify the functionality of our technical debt as use cases in the tree as well)
+- how are we going to "rationalise" our current siloed landscape (and technical debt)?
+- what are the short and long term priorities?
+- what are the milestones and the roadmap?
+- which ideas (for use cases) have been proposed, considered approved or rejected and why?
+
+![Context](../diagrams/out/use-case-development-process.svg#darkable)
+
 ## 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
-```
+Each individual Use Case itself goes through a life-cycle of continuous improvement like:[^1]
+
+![Context](../diagrams/out/use-case-life-cycle.svg#darkable)
 
-[^1]: the life-cycle diagram shown is obviously a simplification
 
 ## Key components
 
@@ -65,9 +71,10 @@ the term --- it is not exactly the same, in our Use Case Tree Method:
   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].
+  like turn-key components for the EKG, 100% reusable delivering "no code"-functionality[^2].
 
-[^1]: [No-code](https://en.wikipedia.org/wiki/No-code_development_platform) or 
+[^1]: the life-cycle diagram shown is obviously a simplification
+[^2]: [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/diagrams/.gitignore

@@ -0,0 +1 @@
+out/

docs/diagrams/include/themes/dark.puml

@@ -0,0 +1,11 @@
+!define BG_MAIN_COLOR      #1A618C
+!define BG_SECONDARY_COLOR #616768
+!define BG_PACKAGE_COLOR   #7a209f
+!define BORDER_COLOR       #EEEEEE
+!define FONT_COLOR         #EEEEEE
+
+skinparam backgroundColor #transparent
+
+' include the general skinparams for both, light and dark
+' to overwrite with the given settings
+!include general.puml

docs/diagrams/include/themes/general.puml

@@ -0,0 +1,159 @@
+!define BORDER_THICKNESS 3
+
+skinparam Padding 4
+skinparam RoundCorner 4
+skinparam Shadowing false
+
+skinparam Default {
+  'FontName "Open Sans Semibold"
+  FontColor FONT_COLOR
+  FontSize 12
+}
+
+skinparam Arrow {
+  Color FONT_COLOR
+  FontColor FONT_COLOR
+  FontStyle Bold
+}
+
+skinparam package {
+  FontColor FONT_COLOR
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+}
+skinparam node {
+  FontColor FONT_COLOR
+  BackgroundColor BG_PACKAGE_COLOR
+  BorderColor BORDER_COLOR
+}
+skinparam component {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+  Style uml2
+}
+
+skinparam database {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+
+skinparam cloud {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+
+skinparam collections {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam Control {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam Boundary {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam Entity {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam interface {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam SequenceParticipantBorderThickness 3
+skinparam sequence {
+  ParticipantBackgroundColor BG_MAIN_COLOR
+  ParticipantBorderColor BORDER_COLOR
+  ParticipantFontStyle normal
+  ParticipantFontColor FONT_COLOR
+  LifeLineBorderColor BORDER_COLOR
+  LifeLineBackgroundColor BG_MAIN_COLOR
+  ArrowColor FONT_COLOR
+  ArrowBorderColor BORDER_COLOR
+  ArrowFontColor FONT_COLOR
+  ArrowThickness 3
+  ActorBackgroundColor BG_MAIN_COLOR
+  ActorBorderColor BORDER_COLOR
+  ActorFontColor FONT_COLOR
+}
+
+' C4 Styling
+' ##################################
+
+skinparam rectangle<<person>> {
+  StereotypeFontColor FONT_COLOR
+  FontColor FONT_COLOR
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  BorderThickness BORDER_THICKNESS
+}
+
+skinparam rectangle<<external_person>> {
+  StereotypeFontColor FONT_COLOR
+  FontColor FONT_COLOR
+  BackgroundColor BG_SECONDARY_COLOR
+  BorderColor BORDER_COLOR
+  BorderThickness BORDER_THICKNESS
+}
+
+skinparam rectangle<<system>> {
+  StereotypeFontColor FONT_COLOR
+  FontColor FONT_COLOR
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  BorderThickness BORDER_THICKNESS
+}
+
+skinparam rectangle<<external_system>> {
+  StereotypeFontColor FONT_COLOR
+  FontColor FONT_COLOR
+  BackgroundColor BG_SECONDARY_COLOR
+  BorderColor BORDER_COLOR
+  BorderThickness BORDER_THICKNESS
+}
+
+skinparam database<<system>> {
+  StereotypeFontColor FONT_COLOR
+  FontColor FONT_COLOR
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  BorderThickness BORDER_THICKNESS
+}
+
+skinparam database<<external_system>> {
+  StereotypeFontColor FONT_COLOR
+  FontColor FONT_COLOR
+  BackgroundColor BG_SECONDARY_COLOR
+  BorderColor BORDER_COLOR
+  BorderThickness BORDER_THICKNESS
+}
+
+skinparam rectangle<<boundary>> {
+  Shadowing false
+  StereotypeFontSize 0
+  BackgroundColor BG_PACKAGE_COLOR
+  StereotypeFontColor FONT_COLOR
+  FontColor FONT_COLOR
+  BorderColor BORDER_COLOR
+  BorderStyle dashed
+  BorderThickness BORDER_THICKNESS
+}
+skinparam rectangle<<container>> {
+  Shadowing false
+  StereotypeFontSize 14
+  BackgroundColor BG_MAIN_COLOR
+  StereotypeFontColor FONT_COLOR
+  FontColor FONT_COLOR
+  BorderColor BORDER_COLOR
+  BorderThickness BORDER_THICKNESS
+}

docs/diagrams/include/themes/light.puml

@@ -0,0 +1,11 @@
+!define BG_MAIN_COLOR      #66BCF0
+!define BG_SECONDARY_COLOR #B4BCBE
+!define BG_PACKAGE_COLOR   #eeb291
+!define BORDER_COLOR       #444444
+!define FONT_COLOR         #444444
+
+skinparam backgroundColor #white
+
+' include the general skinparams for both, light and dark
+' to overwrite with the given settings
+!include general.puml