website-and-documentation/content/en/docs/DOCUMENTATION-GUIDE.md

title	linkTitle	weight	description
Documentation Guide	Documentation Guide	1	Guidelines and templates for creating EDP documentation.

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.

Documentation Principles

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

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

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

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

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

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.

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

Using Templates

Templates are provided for common documentation types:

• Component Documentation: content/en/docs/components/TEMPLATE.md
• Review existing component pages for examples (Forgejo, Kubernetes, Backstage)

Frontmatter

Every markdown file starts with YAML frontmatter:

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

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:

# Good example
task serve

# Configuration example
apiVersion: v1
kind: Service

Testing Documentation

Before committing changes:

# Run all tests
task test

# Build site locally
task build

# Preview changes
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:

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

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
• Component Template: /content/en/docs/components/TEMPLATE.md
• Hugo Documentation: https://gohugo.io/documentation/
• Docsy Theme: https://www.docsy.dev/docs/