diff --git a/content/en/docs/components/_index.md b/content/en/docs/components/_index.md index d93f56b..a50ba3b 100644 --- a/content/en/docs/components/_index.md +++ b/content/en/docs/components/_index.md @@ -32,9 +32,8 @@ The EDP consists of the following main component categories: * **Dev Environments**: Development environment provisioning * **Physical Environments**: Runtime infrastructure - ### Product Component Structure [TODO] Links -![alt text](website-and-documentation_resources_product-structure.svg) \ No newline at end of file +![alt text](website-and-documentation_resources_product-structure.svg) diff --git a/content/en/docs/components/deployments/_index.md b/content/en/docs/components/deployments/_index.md index 3698a67..c68c6ff 100644 --- a/content/en/docs/components/deployments/_index.md +++ b/content/en/docs/components/deployments/_index.md @@ -9,8 +9,8 @@ description: > {{% alert title="Draft" color="warning" %}} **Editorial Status**: This page is currently being developed. -* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX) -* **Assignee**: [Name or Team] +* **Jira Ticket**: [TICKET-6733](https://jira.telekom-mms.com/browse/IPCEICIS-6733) +* **Assignee**: Patrick * **Status**: Draft * **Last Updated**: YYYY-MM-DD * **TODO**: diff --git a/content/en/docs/components/deployments/edgeconnect.md b/content/en/docs/components/deployments/edgeconnect/_index.md similarity index 95% rename from content/en/docs/components/deployments/edgeconnect.md rename to content/en/docs/components/deployments/edgeconnect/_index.md index 8a1d607..d31bd74 100644 --- a/content/en/docs/components/deployments/edgeconnect.md +++ b/content/en/docs/components/deployments/edgeconnect/_index.md @@ -9,8 +9,8 @@ description: > {{% alert title="Draft" color="warning" %}} **Editorial Status**: This page is currently being developed. -* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX) -* **Assignee**: [Name or Team] +* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734) +* **Assignee**: Waldemar * **Status**: Draft * **Last Updated**: YYYY-MM-DD * **TODO**: diff --git a/content/en/docs/components/deployments/edgeconnect-client.md b/content/en/docs/components/deployments/edgeconnect/edgeconnect-client.md similarity index 95% rename from content/en/docs/components/deployments/edgeconnect-client.md rename to content/en/docs/components/deployments/edgeconnect/edgeconnect-client.md index 0b30a77..7c08aca 100644 --- a/content/en/docs/components/deployments/edgeconnect-client.md +++ b/content/en/docs/components/deployments/edgeconnect/edgeconnect-client.md @@ -9,8 +9,8 @@ description: > {{% alert title="Draft" color="warning" %}} **Editorial Status**: This page is currently being developed. -* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX) -* **Assignee**: [Name or Team] +* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734) +* **Assignee**: Waldemar * **Status**: Draft * **Last Updated**: YYYY-MM-DD * **TODO**: diff --git a/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md b/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md new file mode 100644 index 0000000..152d044 --- /dev/null +++ b/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md @@ -0,0 +1,128 @@ +--- +title: "EdgeConnect SDK" +linkTitle: "EdgeConnect SDK" +weight: 10 +description: > + Software Development Kit for establishing EdgeConnect connections +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734) +* **Assignee**: Waldemar +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +## Overview + +[Detailed description of the component - what it is, what it does, and why it exists] + +## Key Features + +* [Feature 1] +* [Feature 2] +* [Feature 3] + +## Purpose in EDP + +[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] + +## Repository + +**Code**: [Link to source code repository] + +**Documentation**: [Link to component-specific documentation] + +## Getting Started + +### Prerequisites + +* [Prerequisite 1] +* [Prerequisite 2] + +### Quick Start + +[Step-by-step guide to get started with this component] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +### Verification + +[How to verify the component is working correctly] + +## Usage Examples + +### [Use Case 1] + +[Example with code/commands showing common use case] + +```bash +# Example commands +``` + +### [Use Case 2] + +[Another common scenario] + +## Integration Points + +* **[Component A]**: [How it integrates] +* **[Component B]**: [How it integrates] +* **[Component C]**: [How it integrates] + +## Architecture + +[Optional: Add architectural diagrams and descriptions] + +### Component Architecture (C4) + +[Add C4 Container or Component diagrams showing the internal structure] + +### Sequence Diagrams + +[Add sequence diagrams showing key interaction flows with other components] + +### Deployment Architecture + +[Add infrastructure and deployment diagrams showing how the component is deployed] + +## Configuration + +[Key configuration options and how to set them] + +## Troubleshooting + +### [Common Issue 1] + +**Problem**: [Description] + +**Solution**: [How to fix] + +### [Common Issue 2] + +**Problem**: [Description] + +**Solution**: [How to fix] + +## Status + +**Maturity**: [Production / Beta / Experimental] + +## Additional Resources + +* [Link to external documentation] +* [Link to community resources] +* [Link to related components] + +## Documentation Notes + +[Instructions for team members filling in this documentation - remove this section once complete] diff --git a/content/en/docs/components/deployments/otc.md b/content/en/docs/components/deployments/otc.md index c958d93..2ee32f5 100644 --- a/content/en/docs/components/deployments/otc.md +++ b/content/en/docs/components/deployments/otc.md @@ -9,8 +9,8 @@ description: > {{% alert title="Draft" color="warning" %}} **Editorial Status**: This page is currently being developed. -* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX) -* **Assignee**: [Name or Team] +* **Jira Ticket**: [TICKET-6733](https://jira.telekom-mms.com/browse/IPCEICIS-6733) +* **Assignee**: Patrick * **Status**: Draft * **Last Updated**: YYYY-MM-DD * **TODO**: diff --git a/content/en/docs/components/documentationsystem.md b/content/en/docs/components/documentationsystem.md new file mode 100644 index 0000000..d3b182a --- /dev/null +++ b/content/en/docs/components/documentationsystem.md @@ -0,0 +1,27 @@ +--- +title: "Documentation System" +linkTitle: "Documentation System" +weight: 100 +description: The developer 'documentation as code' documentation System we use ourselfes and over to use for each development team. +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TICKET-6736](https://jira.telekom-mms.com/browse/IPCEICIS-6736) +* **Assignee**: Stephan +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +The Orchestration manages platform and infrastructure provisioning, providing the foundation for the EDP deployment model. + +## Sub-Components + +* **Infrastructure Provisioning**: Low-level infrastructure deployment (infra-deploy, infra-catalogue) +* **Platform Provisioning**: Platform-level component deployment via Stacks diff --git a/content/en/docs/components/forgejo/actions/_index.md b/content/en/docs/components/forgejo/actions/_index.md new file mode 100644 index 0000000..e450675 --- /dev/null +++ b/content/en/docs/components/forgejo/actions/_index.md @@ -0,0 +1,27 @@ +--- +title: "Forgejo Actions" +linkTitle: "Forgejo Actions" +weight: 20 +description: Forgejo Actions. +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TICKET-6730](https://jira.telekom-mms.com/browse/IPCEICIS-6730) +* **Assignee**: [Name or Team] +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +Forgejo provides source code management, project management, and CI/CD automation for the EDP. + +## Sub-Components + +* **Project Management**: Issue tracking and project management features +* **Actions**: CI/CD automation (see CI/CD section) diff --git a/content/en/docs/components/forgejo/actions.md b/content/en/docs/components/forgejo/actions/actions.md similarity index 97% rename from content/en/docs/components/forgejo/actions.md rename to content/en/docs/components/forgejo/actions/actions.md index c32fe35..c8d4d85 100644 --- a/content/en/docs/components/forgejo/actions.md +++ b/content/en/docs/components/forgejo/actions/actions.md @@ -2,8 +2,7 @@ title: "Forgejo Actions" linkTitle: "Actions" weight: 10 -description: > - GitHub Actions-compatible CI/CD automation +description: GitHub Actions-compatible CI/CD automation --- {{% alert title="Draft" color="warning" %}} diff --git a/content/en/docs/components/forgejo/actions/runner-orchestration.md b/content/en/docs/components/forgejo/actions/runner-orchestration.md new file mode 100644 index 0000000..151fff8 --- /dev/null +++ b/content/en/docs/components/forgejo/actions/runner-orchestration.md @@ -0,0 +1,127 @@ +--- +title: "Runner Orchestration" +linkTitle: "Runner Orchestration" +weight: 30 +description: GARM +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX) +* **Assignee**: [Name or Team] +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +## Overview + +[Detailed description of the component - what it is, what it does, and why it exists] + +## Key Features + +* [Feature 1] +* [Feature 2] +* [Feature 3] + +## Purpose in EDP + +[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] + +## Repository + +**Code**: [Link to source code repository] + +**Documentation**: [Link to component-specific documentation] + +## Getting Started + +### Prerequisites + +* [Prerequisite 1] +* [Prerequisite 2] + +### Quick Start + +[Step-by-step guide to get started with this component] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +### Verification + +[How to verify the component is working correctly] + +## Usage Examples + +### [Use Case 1] + +[Example with code/commands showing common use case] + +```bash +# Example commands +``` + +### [Use Case 2] + +[Another common scenario] + +## Integration Points + +* **[Component A]**: [How it integrates] +* **[Component B]**: [How it integrates] +* **[Component C]**: [How it integrates] + +## Architecture + +[Optional: Add architectural diagrams and descriptions] + +### Component Architecture (C4) + +[Add C4 Container or Component diagrams showing the internal structure] + +### Sequence Diagrams + +[Add sequence diagrams showing key interaction flows with other components] + +### Deployment Architecture + +[Add infrastructure and deployment diagrams showing how the component is deployed] + +## Configuration + +[Key configuration options and how to set them] + +## Troubleshooting + +### [Common Issue 1] + +**Problem**: [Description] + +**Solution**: [How to fix] + +### [Common Issue 2] + +**Problem**: [Description] + +**Solution**: [How to fix] + +## Status + +**Maturity**: [Production / Beta / Experimental] + +## Additional Resources + +* [Link to external documentation] +* [Link to community resources] +* [Link to related components] + +## Documentation Notes + +[Instructions for team members filling in this documentation - remove this section once complete] diff --git a/content/en/docs/components/forgejo/runner.md b/content/en/docs/components/forgejo/actions/runner.md similarity index 100% rename from content/en/docs/components/forgejo/runner.md rename to content/en/docs/components/forgejo/actions/runner.md diff --git a/content/en/docs/components/forgejo/forgejo.md b/content/en/docs/components/forgejo/forgejo.md index 1233068..f363aea 100644 --- a/content/en/docs/components/forgejo/forgejo.md +++ b/content/en/docs/components/forgejo/forgejo.md @@ -1,11 +1,48 @@ --- title: "Forgejo Integration, Extension, and Community Collaboration" +linkTitle: Forgejo Software Forge date: "2025-11-17" description: "Summary of the project's work integrating GARM with Forgejo and contributing key features back to the community." tags: ["Forgejo", "GARM", "CI/CD", "OSS", "Community", "Project Report"] categories: ["Workpackage Results"] +weight: 10 --- +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TICKET-6731](https://jira.telekom-mms.com/browse/IPCEICIS-6731) +* **Assignee**: Daniel +* **Status**: Draft +* **Last Updated**: 2025-11-17 +* **TODO**: + * [ ] Add concrete quick start steps + * [ ] Include prerequisites and access information + * [ ] Create first application tutorial +* **Review/Feedback**: + * [ ] Stephan: + * in general: + * [ ] some parts are worth to go th 'Governance' + * [ ] perhaps we should remove the emojis? + * [ ] perhaps we should avoid the impression that the text was copy/pated from AI + * some details/further ideas: + * [ ] where is it, this Forgejo? Why is it called 'edp.buildth.ing'? + * [ ] what are the components we use - package managament, actions, ... + * [ ] Friendly users? organisations? Public/private stuff? + * [ ] App Management discussions (we don't!)? + * [ ] what about code snippets how forgejo is deployed? SSO? user base? Federation options? + * [ ] storages, Redis, Postgres ... deployment options ... helm charts ... + * [ ] Migrations we did, where is the migration code? + * [ ] git POSIX filesystem concurrency discussion, S/3 bucket + * [ ] what is our general experience? + * [ ] repository centric domain data model + * [ ] how did we develop? which version did we take first? how did we upgrade? + * [ ] which development flows did we use? which pipleines? + * [ ] provide codeberg links for the PRs + * [ ] provide architecture drawings and repo links for the cache registry thing + * [ ] provide a hight level actions arch diagram from the perspective of forgejo - link to the GARM component here +{{% /alert %}} + ## 🧾 Result short description / cognitions Here is the management summary of the work package results: diff --git a/content/en/docs/components/forgejo/project-mgmt.md b/content/en/docs/components/forgejo/project-mgmt.md index 6c856c5..b98dd7f 100644 --- a/content/en/docs/components/forgejo/project-mgmt.md +++ b/content/en/docs/components/forgejo/project-mgmt.md @@ -1,7 +1,7 @@ --- title: "Project Management" -linkTitle: "Project Mgmt" -weight: 10 +linkTitle: "Forgejo Project Mgmt" +weight: 50 description: > Project and issue management capabilities within Forgejo --- diff --git a/content/en/docs/components/orchestration/_index.md b/content/en/docs/components/orchestration/_index.md index 46d2978..6246d1b 100644 --- a/content/en/docs/components/orchestration/_index.md +++ b/content/en/docs/components/orchestration/_index.md @@ -9,8 +9,8 @@ description: > {{% alert title="Draft" color="warning" %}} **Editorial Status**: This page is currently being developed. -* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX) -* **Assignee**: [Name or Team] +* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734) +* **Assignee**: Stephan * **Status**: Draft * **Last Updated**: YYYY-MM-DD * **TODO**: diff --git a/content/en/docs/components/orchestration/infrastructure-provisioning.md b/content/en/docs/components/orchestration/application.md similarity index 93% rename from content/en/docs/components/orchestration/infrastructure-provisioning.md rename to content/en/docs/components/orchestration/application.md index aef2bbd..976aeba 100644 --- a/content/en/docs/components/orchestration/infrastructure-provisioning.md +++ b/content/en/docs/components/orchestration/application.md @@ -1,9 +1,9 @@ --- -title: "Infrastructure Provisioning" -linkTitle: "Infrastructure" -weight: 10 +title: "Application Orchestration" +linkTitle: "Application Orchestration" +weight: 30 description: > - Infrastructure deployment and catalog management (infra-deploy, infra-catalogue) + Application-level component provisioning via Stacks --- {{% alert title="Draft" color="warning" %}} diff --git a/content/en/docs/components/orchestration/infrastructure/_index.md b/content/en/docs/components/orchestration/infrastructure/_index.md new file mode 100644 index 0000000..fc84a9d --- /dev/null +++ b/content/en/docs/components/orchestration/infrastructure/_index.md @@ -0,0 +1,128 @@ +--- +title: "Infrastructure Orchestration" +linkTitle: "Infrastructure Orchestration" +weight: 10 +description: > + Infrastructure deployment and catalog management (infra-deploy, infra-catalogue) +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TICKET-6732](https://jira.telekom-mms.com/browse/IPCEICIS-6732) +* **Assignee**: Martin +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +## Overview + +[Detailed description of the component - what it is, what it does, and why it exists] + +## Key Features + +* [Feature 1] +* [Feature 2] +* [Feature 3] + +## Purpose in EDP + +[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] + +## Repository + +**Code**: [Link to source code repository] + +**Documentation**: [Link to component-specific documentation] + +## Getting Started + +### Prerequisites + +* [Prerequisite 1] +* [Prerequisite 2] + +### Quick Start + +[Step-by-step guide to get started with this component] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +### Verification + +[How to verify the component is working correctly] + +## Usage Examples + +### [Use Case 1] + +[Example with code/commands showing common use case] + +```bash +# Example commands +``` + +### [Use Case 2] + +[Another common scenario] + +## Integration Points + +* **[Component A]**: [How it integrates] +* **[Component B]**: [How it integrates] +* **[Component C]**: [How it integrates] + +## Architecture + +[Optional: Add architectural diagrams and descriptions] + +### Component Architecture (C4) + +[Add C4 Container or Component diagrams showing the internal structure] + +### Sequence Diagrams + +[Add sequence diagrams showing key interaction flows with other components] + +### Deployment Architecture + +[Add infrastructure and deployment diagrams showing how the component is deployed] + +## Configuration + +[Key configuration options and how to set them] + +## Troubleshooting + +### [Common Issue 1] + +**Problem**: [Description] + +**Solution**: [How to fix] + +### [Common Issue 2] + +**Problem**: [Description] + +**Solution**: [How to fix] + +## Status + +**Maturity**: [Production / Beta / Experimental] + +## Additional Resources + +* [Link to external documentation] +* [Link to community resources] +* [Link to related components] + +## Documentation Notes + +[Instructions for team members filling in this documentation - remove this section once complete] diff --git a/content/en/docs/components/orchestration/infrastructure/provider.md b/content/en/docs/components/orchestration/infrastructure/provider.md new file mode 100644 index 0000000..236c0cc --- /dev/null +++ b/content/en/docs/components/orchestration/infrastructure/provider.md @@ -0,0 +1,127 @@ +--- +title: "Provider" +linkTitle: "Provider" +weight: 20 +description: Used Provider we deploy on +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TICKET-6732](https://jira.telekom-mms.com/browse/IPCEICIS-6732) +* **Assignee**: Martin +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +## Overview + +[Detailed description of the component - what it is, what it does, and why it exists] + +## Key Features + +* [Feature 1] +* [Feature 2] +* [Feature 3] + +## Purpose in EDP + +[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] + +## Repository + +**Code**: [Link to source code repository] + +**Documentation**: [Link to component-specific documentation] + +## Getting Started + +### Prerequisites + +* [Prerequisite 1] +* [Prerequisite 2] + +### Quick Start + +[Step-by-step guide to get started with this component] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +### Verification + +[How to verify the component is working correctly] + +## Usage Examples + +### [Use Case 1] + +[Example with code/commands showing common use case] + +```bash +# Example commands +``` + +### [Use Case 2] + +[Another common scenario] + +## Integration Points + +* **[Component A]**: [How it integrates] +* **[Component B]**: [How it integrates] +* **[Component C]**: [How it integrates] + +## Architecture + +[Optional: Add architectural diagrams and descriptions] + +### Component Architecture (C4) + +[Add C4 Container or Component diagrams showing the internal structure] + +### Sequence Diagrams + +[Add sequence diagrams showing key interaction flows with other components] + +### Deployment Architecture + +[Add infrastructure and deployment diagrams showing how the component is deployed] + +## Configuration + +[Key configuration options and how to set them] + +## Troubleshooting + +### [Common Issue 1] + +**Problem**: [Description] + +**Solution**: [How to fix] + +### [Common Issue 2] + +**Problem**: [Description] + +**Solution**: [How to fix] + +## Status + +**Maturity**: [Production / Beta / Experimental] + +## Additional Resources + +* [Link to external documentation] +* [Link to community resources] +* [Link to related components] + +## Documentation Notes + +[Instructions for team members filling in this documentation - remove this section once complete] diff --git a/content/en/docs/components/orchestration/infrastructure/terraform.md b/content/en/docs/components/orchestration/infrastructure/terraform.md new file mode 100644 index 0000000..69e1813 --- /dev/null +++ b/content/en/docs/components/orchestration/infrastructure/terraform.md @@ -0,0 +1,128 @@ +--- +title: "Terrafrom" +linkTitle: "Terraform" +weight: 10 +description: > + Infrastructure deployment and catalog management (infra-deploy, infra-catalogue) +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TICKET-6732](https://jira.telekom-mms.com/browse/IPCEICIS-6732) +* **Assignee**: Martin +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +## Overview + +[Detailed description of the component - what it is, what it does, and why it exists] + +## Key Features + +* [Feature 1] +* [Feature 2] +* [Feature 3] + +## Purpose in EDP + +[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] + +## Repository + +**Code**: [Link to source code repository] + +**Documentation**: [Link to component-specific documentation] + +## Getting Started + +### Prerequisites + +* [Prerequisite 1] +* [Prerequisite 2] + +### Quick Start + +[Step-by-step guide to get started with this component] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +### Verification + +[How to verify the component is working correctly] + +## Usage Examples + +### [Use Case 1] + +[Example with code/commands showing common use case] + +```bash +# Example commands +``` + +### [Use Case 2] + +[Another common scenario] + +## Integration Points + +* **[Component A]**: [How it integrates] +* **[Component B]**: [How it integrates] +* **[Component C]**: [How it integrates] + +## Architecture + +[Optional: Add architectural diagrams and descriptions] + +### Component Architecture (C4) + +[Add C4 Container or Component diagrams showing the internal structure] + +### Sequence Diagrams + +[Add sequence diagrams showing key interaction flows with other components] + +### Deployment Architecture + +[Add infrastructure and deployment diagrams showing how the component is deployed] + +## Configuration + +[Key configuration options and how to set them] + +## Troubleshooting + +### [Common Issue 1] + +**Problem**: [Description] + +**Solution**: [How to fix] + +### [Common Issue 2] + +**Problem**: [Description] + +**Solution**: [How to fix] + +## Status + +**Maturity**: [Production / Beta / Experimental] + +## Additional Resources + +* [Link to external documentation] +* [Link to community resources] +* [Link to related components] + +## Documentation Notes + +[Instructions for team members filling in this documentation - remove this section once complete] diff --git a/content/en/docs/components/orchestration/platform-provisioning.md b/content/en/docs/components/orchestration/platform.md similarity index 97% rename from content/en/docs/components/orchestration/platform-provisioning.md rename to content/en/docs/components/orchestration/platform.md index 162ef9f..baa528f 100644 --- a/content/en/docs/components/orchestration/platform-provisioning.md +++ b/content/en/docs/components/orchestration/platform.md @@ -1,6 +1,6 @@ --- -title: "Platform Provisioning" -linkTitle: "Platform" +title: "Platform Orchestration" +linkTitle: "Platform Orchestration" weight: 20 description: > Platform-level component provisioning via Stacks diff --git a/content/en/docs/components/orchestration/stacks.md b/content/en/docs/components/orchestration/stacks/_index.md similarity index 95% rename from content/en/docs/components/orchestration/stacks.md rename to content/en/docs/components/orchestration/stacks/_index.md index da659c6..f8d30b1 100644 --- a/content/en/docs/components/orchestration/stacks.md +++ b/content/en/docs/components/orchestration/stacks/_index.md @@ -1,7 +1,7 @@ --- title: "Stacks" linkTitle: "Stacks" -weight: 20 +weight: 40 description: > Platform-level component provisioning via Stacks --- @@ -9,8 +9,8 @@ description: > {{% alert title="Draft" color="warning" %}} **Editorial Status**: This page is currently being developed. -* **Jira Ticket**: [TICKET-6418](https://your-jira/browse/TICKET-XXX) -* **Assignee**: [Name or Team] +* **Jira Ticket**: [TICKET-6729](https://jira.telekom-mms.com/browse/IPCEICIS-6729) +* **Assignee**: Stephan * **Status**: Draft * **Last Updated**: YYYY-MM-DD * **TODO**: diff --git a/content/en/docs/components/orchestration/stacks/component-1.md b/content/en/docs/components/orchestration/stacks/component-1.md new file mode 100644 index 0000000..4f6b18c --- /dev/null +++ b/content/en/docs/components/orchestration/stacks/component-1.md @@ -0,0 +1,128 @@ +--- +title: "Component 1" +linkTitle: "Component 1" +weight: 20 +description: > + Component 1 +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TBD] +* **Assignee**: [Name or Team] +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +## Overview + +[Detailed description of the component - what it is, what it does, and why it exists] + +## Key Features + +* [Feature 1] +* [Feature 2] +* [Feature 3] + +## Purpose in EDP + +[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] + +## Repository + +**Code**: [Link to source code repository] + +**Documentation**: [Link to component-specific documentation] + +## Getting Started + +### Prerequisites + +* [Prerequisite 1] +* [Prerequisite 2] + +### Quick Start + +[Step-by-step guide to get started with this component] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +### Verification + +[How to verify the component is working correctly] + +## Usage Examples + +### [Use Case 1] + +[Example with code/commands showing common use case] + +```bash +# Example commands +``` + +### [Use Case 2] + +[Another common scenario] + +## Integration Points + +* **[Component A]**: [How it integrates] +* **[Component B]**: [How it integrates] +* **[Component C]**: [How it integrates] + +## Architecture + +[Optional: Add architectural diagrams and descriptions] + +### Component Architecture (C4) + +[Add C4 Container or Component diagrams showing the internal structure] + +### Sequence Diagrams + +[Add sequence diagrams showing key interaction flows with other components] + +### Deployment Architecture + +[Add infrastructure and deployment diagrams showing how the component is deployed] + +## Configuration + +[Key configuration options and how to set them] + +## Troubleshooting + +### [Common Issue 1] + +**Problem**: [Description] + +**Solution**: [How to fix] + +### [Common Issue 2] + +**Problem**: [Description] + +**Solution**: [How to fix] + +## Status + +**Maturity**: [Production / Beta / Experimental] + +## Additional Resources + +* [Link to external documentation] +* [Link to community resources] +* [Link to related components] + +## Documentation Notes + +[Instructions for team members filling in this documentation - remove this section once complete] diff --git a/content/en/docs/components/orchestration/stacks/component-2.md b/content/en/docs/components/orchestration/stacks/component-2.md new file mode 100644 index 0000000..0244aa7 --- /dev/null +++ b/content/en/docs/components/orchestration/stacks/component-2.md @@ -0,0 +1,128 @@ +--- +title: "Component 2" +linkTitle: "Component 2" +weight: 30 +description: > + Component 2 +--- + +{{% alert title="Draft" color="warning" %}} +**Editorial Status**: This page is currently being developed. + +* **Jira Ticket**: [TBD] +* **Assignee**: [Name or Team] +* **Status**: Draft +* **Last Updated**: YYYY-MM-DD +* **TODO**: + * [ ] Add detailed component description + * [ ] Include usage examples and code samples + * [ ] Add architecture diagrams + * [ ] Review and finalize content +{{% /alert %}} + +## Overview + +[Detailed description of the component - what it is, what it does, and why it exists] + +## Key Features + +* [Feature 1] +* [Feature 2] +* [Feature 3] + +## Purpose in EDP + +[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] + +## Repository + +**Code**: [Link to source code repository] + +**Documentation**: [Link to component-specific documentation] + +## Getting Started + +### Prerequisites + +* [Prerequisite 1] +* [Prerequisite 2] + +### Quick Start + +[Step-by-step guide to get started with this component] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +### Verification + +[How to verify the component is working correctly] + +## Usage Examples + +### [Use Case 1] + +[Example with code/commands showing common use case] + +```bash +# Example commands +``` + +### [Use Case 2] + +[Another common scenario] + +## Integration Points + +* **[Component A]**: [How it integrates] +* **[Component B]**: [How it integrates] +* **[Component C]**: [How it integrates] + +## Architecture + +[Optional: Add architectural diagrams and descriptions] + +### Component Architecture (C4) + +[Add C4 Container or Component diagrams showing the internal structure] + +### Sequence Diagrams + +[Add sequence diagrams showing key interaction flows with other components] + +### Deployment Architecture + +[Add infrastructure and deployment diagrams showing how the component is deployed] + +## Configuration + +[Key configuration options and how to set them] + +## Troubleshooting + +### [Common Issue 1] + +**Problem**: [Description] + +**Solution**: [How to fix] + +### [Common Issue 2] + +**Problem**: [Description] + +**Solution**: [How to fix] + +## Status + +**Maturity**: [Production / Beta / Experimental] + +## Additional Resources + +* [Link to external documentation] +* [Link to community resources] +* [Link to related components] + +## Documentation Notes + +[Instructions for team members filling in this documentation - remove this section once complete] diff --git a/content/en/docs/DOCUMENTATION-GUIDE.md b/content/en/docs/documentation-guide/_index.md similarity index 50% rename from content/en/docs/DOCUMENTATION-GUIDE.md rename to content/en/docs/documentation-guide/_index.md index 5ed89f4..fa0ccb3 100644 --- a/content/en/docs/DOCUMENTATION-GUIDE.md +++ b/content/en/docs/documentation-guide/_index.md @@ -1,41 +1,44 @@ --- -title: "Documentation Guide" -linkTitle: "Documentation Guide" +title: "WiP Documentation Guide" +linkTitle: "WiP Doc Guide" weight: 1 -description: > - Guidelines and templates for creating EDP documentation. +description: Guidelines and templates for creating EDP documentation. This page will be removed in the final documentation. --- +{{% alert title="WiP - Only during creation phase" %}} +This page will be removed in the final documentation. +{{% /alert %}} + ## Purpose -This guide helps team members create consistent, high-quality documentation for the Edge Developer Platform. The documentation serves developers, engineers, and auditors who need to understand and use the platform. +This guide helps team members create consistent, high-quality documentation for the Edge Developer Platform. + ## Documentation Principles -### Focus on Outcomes +### 1. Focus on Outcomes -* Describe what the platform does and how to use it -* Emphasize practical usage over implementation details -* Include links to repositories for deeper technical information +1. Describe how the platform is comprised and which Products we deliver +2. If you need inspiration for our EDP product structure look at [EDP product structure tree](../components/website-and-documentation_resources_product-structure.svg) +2. Include links to repositories for deeper technical information or for not beeing too verbose and redundant with existing doumentation within the IPCEI-CIS scope or our EDP repos scope. -### Write for the Audience +### 2. Write for the Audience -* **Developers**: How to use the platform, deploy applications, integrate services -* **Engineers**: Architecture, operational procedures, troubleshooting -* **Auditors**: Project history, decisions, compliance information +1. **Developers**: How to use the software products +2. **Engineers**: Architecture +3. **Auditors**: Project history, decisions, compliance information -### Keep It Concise +### 3. Keep It Concise -* Top-down approach: start with overview, drill down as needed -* Less is more - avoid deep nested structures -* Use templates to maintain consistency +1. Top-down approach: start with overview, drill down as needed +2. Less is more - avoid deep nested structures +3. Avoid emojis +4. **When using AI**: Review the text that you paste, check integration into the rest of the documentation -### Maintain Quality +### 4. Maintain Quality -* Use present tense ("The system processes..." not "will process") -* Keep information up to date -* Test examples and procedures before documenting -* Run `task test` before committing changes +1. Use present tense ("The system processes..." not "will process") +2. Run `task test:quick` before committing changes ## Documentation Structure @@ -47,7 +50,13 @@ High-level introduction to EDP, target audience, purpose, and product structure. **Content focus**: Why EDP exists, who uses it, what it provides -### 2. Components +### 2. Getting Started + +Onboarding guides and quick start instructions. + +**Content focus**: Prerequisites, step-by-step setup, first application deployment + +### 3. Components Detailed documentation for each platform component. @@ -55,12 +64,6 @@ Detailed documentation for each platform component. **Template**: Use `components/TEMPLATE.md` as starting point -### 3. Getting Started - -Onboarding guides and quick start instructions. - -**Content focus**: Prerequisites, step-by-step setup, first application deployment - ### 4. Operations Deployment, monitoring, troubleshooting, and maintenance procedures. @@ -75,16 +78,30 @@ Project history, architecture decisions, compliance, and audit information. ## Writing Documentation -### Using Templates +### Components -Templates are provided for common documentation types: +#### Using Templates + +In section 'Components' Templates are provided for common documentation types: * **Component Documentation**: `content/en/docs/components/TEMPLATE.md` -* Review existing component pages for examples (Forgejo, Kubernetes, Backstage) + +#### Content Structure + +Follow this pattern for component documentation: + +1. **Overview**: What it is and what it does +2. **Key Features**: Bullet list of main capabilities +3. **Purpose in EDP**: Why it's part of the platform +4. **Getting Started**: Quick start guide +5. **Usage Examples**: Common scenarios +6. **Integration Points**: How it connects to other components +7. **Status**: Current maturity level +8. **Documentation Notes**: Instructions for filling in details (remove when complete) ### Frontmatter -Every markdown file starts with YAML frontmatter: +Every markdown file starts with YAML frontmatter according to [Docsy](https://www.docsy.dev/docs/adding-content/content/#page-frontmatter): ```yaml --- @@ -101,48 +118,13 @@ description: > * **weight**: Sort order (lower numbers appear first) * **description**: Brief summary for SEO and page previews -### Content Structure - -Follow this pattern for component documentation: - -1. **Overview**: What it is and what it does -2. **Key Features**: Bullet list of main capabilities -3. **Purpose in EDP**: Why it's part of the platform -4. **Getting Started**: Quick start guide -5. **Usage Examples**: Common scenarios -6. **Integration Points**: How it connects to other components -7. **Status**: Current maturity level -8. **Documentation Notes**: Instructions for filling in details (remove when complete) - -### Markdown Style - -* Use `*` for bullet lists (not `-`) -* Add blank lines around headings and lists -* Specify language for code blocks: ` ```bash ` or ` ```yaml ` -* Use relative links for internal pages - -### Including Code Examples - -Always specify the language: - -```bash -# Good example -task serve -``` - -```yaml -# Configuration example -apiVersion: v1 -kind: Service -``` - ## Testing Documentation Before committing changes: ```bash # Run all tests -task test +task test:quick # Build site locally task build @@ -151,13 +133,6 @@ task build task serve ``` -The test suite checks: - -* Markdown syntax (markdownlint) -* HTML validity -* Broken links -* Hugo build success - ## Adding New Sections When adding a new documentation section: @@ -168,34 +143,6 @@ When adding a new documentation section: 4. Update navigation in parent `_index.md` if needed 5. Test with `task test` -## Tips for Good Documentation - -### Do - -* Write clearly and concisely -* Use examples and code samples -* Include links to repositories and external resources -* Update documentation when features change -* Test procedures before documenting them -* Use templates for consistency - -### Don't - -* Create deep nested structures (keep it flat) -* Document implementation details extensively (link to code instead) -* Use future tense ("will do" → "does") -* Add documentation for incomplete features -* Forget to test your changes - -## Getting Help - -For questions about documentation: - -* Check existing pages for examples -* Review `doc/README-technical-writer.md` for Hugo/Docsy details -* Ask team members for review before committing -* Use `task serve` to preview changes locally - ## Reference * **Main README**: `/doc/README-technical-writer.md` diff --git a/content/en/docs/governance/_index.md b/content/en/docs/governance/_index.md index 9ebbad2..c5ab30c 100644 --- a/content/en/docs/governance/_index.md +++ b/content/en/docs/governance/_index.md @@ -9,8 +9,8 @@ description: > {{% alert title="Draft" color="warning" %}} **Editorial Status**: This page is currently being developed. -* **Jira Ticket**: TBD -* **Assignee**: Team +* **Jira Ticket**: [TICKET-6737](https://jira.telekom-mms.com/browse/IPCEICIS-6737) +* **Assignee**: Sophie * **Status**: Draft - Structure only * **Last Updated**: 2025-11-16 * **TODO**: