diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 92e4dcb..467e928 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -6,24 +6,12 @@ menu: weight: 20 --- -{{% 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 %}} - # Edge Developer Platform (EDP) Documentation Welcome to the EDP documentation. This documentation serves developers, engineers, and auditors who want to understand, use, and audit the Edge Developer Platform. +{{< likec4-view view="developer-landscape-with-foundry" project="architecture" title="High level eDF Vision: DevOps enhanced by Platform integration" >}} + ## Target Audience * **Developers & Engineers**: Learn how to use the platform, deploy applications, and integrate services diff --git a/content/en/docs/documentation-guide/_index.md b/content/en/docs/documentation-guide/_index.md deleted file mode 100644 index fa0ccb3..0000000 --- a/content/en/docs/documentation-guide/_index.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: "WiP Documentation Guide" -linkTitle: "WiP Doc Guide" -weight: 1 -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. - - -## Documentation Principles - -### 1. Focus on Outcomes - -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. - -### 2. Write for the Audience - -1. **Developers**: How to use the software products -2. **Engineers**: Architecture -3. **Auditors**: Project history, decisions, compliance information - -### 3. Keep It Concise - -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 - -### 4. Maintain Quality - -1. Use present tense ("The system processes..." not "will process") -2. Run `task test:quick` before committing changes - -## Documentation Structure - -The EDP documentation is organized into five main sections: - -### 1. Platform Overview - -High-level introduction to EDP, target audience, purpose, and product structure. - -**Content focus**: Why EDP exists, who uses it, what it provides - -### 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. - -**Content focus**: What each component does, how to use it, integration points - -**Template**: Use `components/TEMPLATE.md` as starting point - -### 4. Operations - -Deployment, monitoring, troubleshooting, and maintenance procedures. - -**Content focus**: How to operate the platform, resolve issues, maintain health - -### 5. Governance - -Project history, architecture decisions, compliance, and audit information. - -**Content focus**: Why decisions were made, project evolution, external relations - -## Writing Documentation - -### Components - -#### Using Templates - -In section 'Components' Templates are provided for common documentation types: - -* **Component Documentation**: `content/en/docs/components/TEMPLATE.md` - -#### 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 according to [Docsy](https://www.docsy.dev/docs/adding-content/content/#page-frontmatter): - -```yaml ---- -title: "Full Page Title" -linkTitle: "Short Nav Title" -weight: 10 -description: > - Brief description for search and previews. ---- -``` - -* **title**: Full page title (appears in page header) -* **linkTitle**: Shorter title for navigation menu -* **weight**: Sort order (lower numbers appear first) -* **description**: Brief summary for SEO and page previews - -## Testing Documentation - -Before committing changes: - -```bash -# Run all tests -task test:quick - -# Build site locally -task build - -# Preview changes -task serve -``` - -## Adding New Sections - -When adding a new documentation section: - -1. Create directory: `content/en/docs/[section-name]/` -2. Create index file: `_index.md` with frontmatter -3. Add weight to control sort order -4. Update navigation in parent `_index.md` if needed -5. Test with `task test` - -## Reference - -* **Main README**: `/doc/README-technical-writer.md` -* **Component Template**: `/content/en/docs/components/TEMPLATE.md` -* **Hugo Documentation**: -* **Docsy Theme**: