doc(README): update documentation structure and add getting started section

README.md

@@ -52,7 +52,44 @@ The EDP documentation is subject to this repo in folder [`docs`](./docs/). It is
 
 Thus it can be read in four ways by
 
-1. [accessing the Backstage portal in a running Demo EDP](./docs/introduction/index.md#doc-in-backstage-in-a-running-demo-edp)
+1. [accessing the Backstage portal in a running Demo EDP](#doc-in-backstage-in-a-running-demo-edp)
-2. [accessing the Backstage portal in a Demo EDP setup on your computer](./docs/introduction/index.md#doc-in-backstage-in-a-demo-edp-setup-on-your-computer)
+2. [accessing the Backstage portal in a Demo EDP setup on your computer](#doc-in-backstage-in-a-demo-edp-setup-on-your-computer)
-3. [browsing the documentaion repository](./docs/introduction/index.md#doc-in-the-repository)
+3. [browsing the documentaion repository](#doc-in-the-repository)
-4. [browsing in a Backstage simulation on your computer](./docs/introduction/index.md#doc-in-a-backstage-simulation)
+4. [browsing in a Backstage simulation on your computer](#doc-in-a-backstage-simulation)
+
+## Getting Started
+
+So get started by reading the doc in one of these ways, sorted from 'easy' to 'opinionated' accessibility:
+
+### Doc in Backstage in a running Demo EDP
+
+The documentation can be easily accessed through a Demo EDP instance hosted on our Open Sovereign Cloud (OSC).
+Thus there you have a Backstage-Developer Portal running, containing the EDP documentation.
+
+Simply log in to Demo EDP Backstage to read through the documentation:
+
+* [EDP Documentation URL](https://edf-cc1.cx.fg1.ffm.osc.live/docs/edppoc/component/edp-documentation)
+* Username: user1
+* Password: PpMpfZYICG9MRRF-3QBY2Zz1-+URYB6+-JRe
+
+### Doc in the repository
+  
+> Hint: the following link only works when you are in the repo (not in Backstage), like [the central one](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/edp-doc)
+
+If you prefer direct access, the content of our documentation is centrally defined and maintained within the [docs folder of this repository](./docs/contents.md).
+
+### Doc in a Backstage simulation
+
+> Hint: the following link only works when you are in the repo (not in Backstage), like [the central one](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/edp-doc)
+
+The Backstage TechDocs embedding can also be [emulated in a Backstage portal frame running on your computer](./live-preview-integration/README-backstage-local.md).
+
+### Doc in Backstage in a Demo EDP setup on your computer
+
+As `edpbuilder` is a infrastructure agnostic platform orchestrator, you also can boostrap the EDP Demo on your own laptop!
+
+Using the edpbuilder, you can set up a local Demo EDP that comes with a Backstage instance containing the documentation:
+
+> Hint: the following link only works when you are in the repo (not in Backstage), like [the central one](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/edp-doc)
+
+[How to set up a local IDP on a kind cluster](./docs/user-documentation/edpbuilder.md)

docs/contents.md

@@ -0,0 +1,44 @@
+# EDP Documentation
+
+The documentation consists of two parts
+
+* User Documentation
+* Technical Documentation
+
+Both are outlined in the following.
+
+## User Documentation
+
+### 📋 Outline
+- [What is it? (short description what the software does, max 3 sentences)](#what-is-it)
+  - A couple of use cases (different scopes)
+  - Why do I need / want this? When should I pass?
+  - Compare with other platforms
+  - Compare with well-known tools (what parts of my stack / pipeline does this cover?)
+    - argo -> vercel
+    - monitoring -> data dog
+    - forgejo -> graphite
+- [Main features (brief list of main features and enablers - why it is in the stack)](#main-features)
+  - what are our opinions / core principles and believes that are backed in?
+    - k8s > *
+  - Developer Portal: Backstage
+- [Quick start guide](#quick-start-guide)
+- [Configuration](#configuration)
+  - structure of the poc (where / how can I change something?)
+  - how does it work? (bootstrapping++)
+- [Known Issues / TODOs](#known-issues)
+- [References (documentation links etc...)](#references)
+
+### 🧐 What is it?
+
+10:40 THU
+
+### 📦 Main features
+
+### ⏱️ Quick start guide
+
+### ⚙️ Configuration
+
+### 🔗 References
+
+## Technical Documentation  

docs/introduction/index.md

@@ -1,70 +0,0 @@
-# EDP Documentation
-
-## How to access the Documentation
-
-The EDP documentation is subject to this repo in folder [`docs`](./docs/). It is created in the [`mkdocs`](https://www.mkdocs.org/) documentation format and natively embedded in the [`Backstage TechDocs` documentation technology](https://backstage.io/docs/features/techdocs/).
-
-Thus it can be read in four ways:
-
-### Doc in Backstage in a running Demo EDP
-
-The documentation can be easily accessed through a Demo EDP instance hosted on our Open Sovereign Cloud (OSC).
-
-Thus there you have a Backstage-Developer Portal running, containing the EDP documentation.
-
-Simply log in to [Demo EDP Backstage](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW-CICD/stacks) to read through the documentation.
-
-* [EDP Documentation URL](https://edf-cc1.cx.fg1.ffm.osc.live/docs/edppoc/component/edp-documentation)
-* Username: user1
-* Password: PpMpfZYICG9MRRF-3QBY2Zz1-+URYB6+-JRe
-
-### Doc in Backstage in a Demo EDP setup on your computer
-
-As `edpbuilder` is a infrastructure agnostic platform orchestrator, you also can boostrap the EDP Demo on your own laptop!
-
-Using the edpbuilder, you can set up a local Demo EDP that comes with a Backstage instance containing the documentation:
-[How to set up a local IDP on a kind cluster](./docs/user-documentation/edpbuilder.md)
-
-### Doc in the repository
-  
-If you prefer direct access, the content of our documentation is centrally defined and maintained within the [docs folder of this repository](./docs/).
-
-### Doc in a Backstage simulation
-
-The Backstage TechDocs embedding can also be [emulated in a Backstage portal frame running on your computer](./live-preview-integration/README-backstage-local.md). 
-
-## User Documentation
-
-### 📋 Outline
-- [What is it? (short description what the software does, max 3 sentences)](#what-is-it)
-  - A couple of use cases (different scopes)
-  - Why do I need / want this? When should I pass?
-  - Compare with other platforms
-  - Compare with well-known tools (what parts of my stack / pipeline does this cover?)
-    - argo -> vercel
-    - monitoring -> data dog
-    - forgejo -> graphite
-- [Main features (brief list of main features and enablers - why it is in the stack)](#main-features)
-  - what are our opinions / core principles and believes that are backed in?
-    - k8s > *
-  - Developer Portal: Backstage
-- [Quick start guide](#quick-start-guide)
-- [Configuration](#configuration)
-  - structure of the poc (where / how can I change something?)
-  - how does it work? (bootstrapping++)
-- [Known Issues / TODOs](#known-issues)
-- [References (documentation links etc...)](#references)
-
-### 🧐 What is it?
-
-10:40 THU
-
-### 📦 Main features
-
-### ⏱️ Quick start guide
-
-### ⚙️ Configuration
-
-### 🔗 References
-
-## Technical Documentation  

mkdocs.yaml

@@ -3,7 +3,7 @@ site_description: 'EDP documentation'
 
 nav:
   - Home: index.md
-  - Contents: introduction/index.md
+  - Contents: contents.md
   - User Documentation: 
     - ArgoCD: user-documentation/argocd.md
     - Backstage: user-documentation/backstage.md