docs(): removed internal documentation chapter, added an exsiting high level vision chart on the intro page
This commit is contained in:
parent
9c16f17968
commit
ae95fb86a8
2 changed files with 2 additions and 165 deletions
|
|
@ -6,24 +6,12 @@ menu:
|
||||||
weight: 20
|
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
|
# 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.
|
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
|
## Target Audience
|
||||||
|
|
||||||
* **Developers & Engineers**: Learn how to use the platform, deploy applications, and integrate services
|
* **Developers & Engineers**: Learn how to use the platform, deploy applications, and integrate services
|
||||||
|
|
|
||||||
|
|
@ -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**: <https://gohugo.io/documentation/>
|
|
||||||
* **Docsy Theme**: <https://www.docsy.dev/docs/>
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue