docs(forgejo): some restructuring and review - tbc

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)
+![alt text](website-and-documentation_resources_product-structure.svg)

content/en/docs/components/forgejo/actions.md

@@ -1,9 +1,8 @@
 ---
 title: "Forgejo Actions"
 linkTitle: "Actions"
-weight: 10
+weight: 20
-description: >
+description: GitHub Actions-compatible CI/CD automation
-  GitHub Actions-compatible CI/CD automation
 ---
 
 {{% alert title="Draft" color="warning" %}}

content/en/docs/components/forgejo/forgejo.md

@@ -1,11 +1,40 @@
 ---
 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**: 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? why is it called 'edp.buildth.ing'?
+      * Friendly users? organisations? Public/private stuff?
+      * App Management discussions (we don't!)?
+      * what about code snippets how forgejo is deployed? 
+      * Migrations we did, where is the migration code?
+      * what is our general experience?
+      * ...
+{{% /alert %}}
+
 ## 🧾 Result short description / cognitions
 
 Here is the management summary of the work package results:

content/en/docs/components/forgejo/project-mgmt.md

@@ -1,7 +1,7 @@
 ---
 title: "Project Management"
 linkTitle: "Project Mgmt"
-weight: 10
+weight: 50
 description: >
   Project and issue management capabilities within Forgejo
 ---

content/en/docs/components/forgejo/runner-orchestration.md

@@ -0,0 +1,127 @@
+---
+title: "Runner Orchestration"
+linkTitle: "Runner Orchestration"
+weight: 40
+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]

content/en/docs/components/forgejo/runner.md

@@ -1,7 +1,7 @@
 ---
 title: "Action Runner"
 linkTitle: "Runner"
-weight: 20
+weight: 30
 description: >
   Self-hosted runner infrastructure with orchestration capabilities
 ---

content/en/docs/documentation-guide/_index.md

@@ -1,41 +1,44 @@
 ---
-title: "Documentation Guide"
+title: "WiP Documentation Guide"
-linkTitle: "Documentation Guide"
+linkTitle: "WiP Doc Guide"
 weight: 1
-description: >
+description: Guidelines and templates for creating EDP documentation. This page will be removed in the final documentation.
-  Guidelines and templates for creating EDP 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
+1. Describe how the platform is comprised and which Products we deliver
-* Emphasize practical usage over implementation details
+2. If you need inspiration for our EDP product structure look at [EDP product structure tree](../components/website-and-documentation_resources_product-structure.svg)
-* Include links to repositories for deeper technical information
+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
+1. **Developers**: How to use the software products
-* **Engineers**: Architecture, operational procedures, troubleshooting
+2. **Engineers**: Architecture
-* **Auditors**: Project history, decisions, compliance information
+3. **Auditors**: Project history, decisions, compliance information
 
-### Keep It Concise
+### 3. Keep It Concise
 
-* Top-down approach: start with overview, drill down as needed
+1. Top-down approach: start with overview, drill down as needed
-* Less is more - avoid deep nested structures
+2. Less is more - avoid deep nested structures
-* Use templates to maintain consistency
+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")
+1. Use present tense ("The system processes..." not "will process")
-* Keep information up to date
+2. Run `task test:quick` before committing changes
-* Test examples and procedures before documenting
-* Run `task test` 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`