Skip to content

25. Contributing to Documentation

25.1 Adding Images

When adding screenshots or diagrams:

  1. Use descriptive file names: twitch-dashboard-stream-key.png not screenshot1.png
  2. Optimize size: Max 500KB per image; use PNG for screenshots, SVG for diagrams
  3. Always include alt text: 
    ![Screenshot of Twitch dashboard showing stream key location](images/twitch-dashboard-stream-key.png)
  4. Store in: docs/images/{section}/ (e.g., docs/images/services/twitch-dashboard.png)

25.2 Style Guide

25.2.1 Terminology

Use consistent terminology and capitalization throughout documentation:

  • Docker (not "docker" or "DOCKER")
  • GitHub (not "github" or "GITHUB")
  • docker compose (not "docker-compose" or "Docker Compose")
  • FFmpeg (not "ffmpeg" or "FFMPEG")
  • nginx (not "Nginx" or "NGINX")
  • stream key (lowercase in body text)
  • environment variable (not "env var" in formal documentation)

25.2.2 Headings

  • Use sentence case: "Quick start guide" not "Quick Start Guide"
  • Keep headings short and descriptive
  • Don't skip heading levels (h2 → h4)

25.2.3 Code Blocks

Always include a language tag:

```bash
docker compose up
```

For placeholders, use angle brackets:

rtmp://<relay-ip>:1935/relay
  • Use descriptive link text (not "click here")
  • Add {target="_blank"} for external links
  • Use relative paths for internal links: ../services/twitch.md

25.3 Front Matter

All documentation pages should include front matter:

---
title: Page Title
description: One-sentence summary for search
audience: users|operators|developers
doc_type: tutorial|howto|explanation|reference
tags: [relevant, tags]
lastReviewed: YYYY-MM-DD
version: 1.x
---

25.4 Avoiding Staleness

  • Don't hardcode version numbers in prose (use "latest" or reference variables)
  • Don't include test counts or specific numbers that change frequently
  • Don't duplicate lists that are maintained elsewhere (link to the source instead)
  • Update lastReviewed date when making significant changes

25.5 Testing Documentation

Before submitting:

  1. Build locally: mkdocs serve
  2. Check for broken links (CI will verify)
  3. Verify code examples are copy-pasteable
  4. Test any commands/examples you've added

25.6 See Also