docs(forgejo): some restructuring and review - tbc
This commit is contained in:
parent
9b6c586e20
commit
47b0c404f3
7 changed files with 212 additions and 111 deletions
|
|
@ -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
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,8 @@
|
|||
---
|
||||
title: "Forgejo Actions"
|
||||
linkTitle: "Actions"
|
||||
weight: 10
|
||||
description: >
|
||||
GitHub Actions-compatible CI/CD automation
|
||||
weight: 20
|
||||
description: GitHub Actions-compatible CI/CD automation
|
||||
---
|
||||
|
||||
{{% alert title="Draft" color="warning" %}}
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: "Project Management"
|
||||
linkTitle: "Project Mgmt"
|
||||
weight: 10
|
||||
weight: 50
|
||||
description: >
|
||||
Project and issue management capabilities within Forgejo
|
||||
---
|
||||
|
|
|
|||
127
content/en/docs/components/forgejo/runner-orchestration.md
Normal file
127
content/en/docs/components/forgejo/runner-orchestration.md
Normal file
|
|
@ -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]
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: "Action Runner"
|
||||
linkTitle: "Runner"
|
||||
weight: 20
|
||||
weight: 30
|
||||
description: >
|
||||
Self-hosted runner infrastructure with orchestration capabilities
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue