204 lines
5.2 KiB
Markdown
204 lines
5.2 KiB
Markdown
---
|
|
title: "Documentation Guide"
|
|
linkTitle: "Documentation Guide"
|
|
weight: 1
|
|
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/>
|