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

title	linkTitle	weight	description
WiP Documentation Guide	WiP Doc Guide	1	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
3. 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:

---
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:

# 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/