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

---
title: "Documentation Guide"
linkTitle: "Documentation Guide"
weight: 100
description: >
  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:

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

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

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