diff --git a/README.md b/README.md index b7275a5..1a89faf 100644 --- a/README.md +++ b/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) -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) -3. [browsing the documentaion repository](./docs/introduction/index.md#doc-in-the-repository) -4. [browsing in a Backstage simulation on your computer](./docs/introduction/index.md#doc-in-a-backstage-simulation) +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](#doc-in-backstage-in-a-demo-edp-setup-on-your-computer) +3. [browsing the documentaion repository](#doc-in-the-repository) +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) diff --git a/docs/contents.md b/docs/contents.md new file mode 100644 index 0000000..30ecc7f --- /dev/null +++ b/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 diff --git a/docs/introduction/index.md b/docs/introduction/index.md deleted file mode 100644 index dbd1975..0000000 --- a/docs/introduction/index.md +++ /dev/null @@ -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 diff --git a/mkdocs.yaml b/mkdocs.yaml index e809f98..1f515db 100644 --- a/mkdocs.yaml +++ b/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