forked from DevFW-CICD/edp-doc
doc(README): update documentation structure and add getting started section
This commit is contained in:
Stephan Lo
parent
8d17325bcd
commit
df186af47c
4 changed files with 86 additions and 75 deletions
45
README.md
45
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)
|
||||
|
|
|
|||
44
docs/contents.md
Normal file
44
docs/contents.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue