Coach WattsDocumentation
Sign In

Writing Documentation

Guidelines and templates for creating consistent, high-quality documentation for Coach Watts.

This guide outlines the standards for creating both athlete-facing and developer-facing documentation within the Coach Watts platform.

!IMPORTANTPublic Visibility: All documentation is public and accessible to non-authenticated users. Do not include sensitive information, private API keys, or internal-only credentials in any .md files.

1. Directory Structure

All documentation is stored in the content/documentation/ directory.

  • 1.athletes/: End-user guides (setup, features, metrics).
  • 2.developers/: Technical documentation (API, authentication, architecture).

Ordering

We use numeric prefixes in filenames (e.g., 1.getting-started.md) to control the sort order in the sidebar navigation. The prefixes are stripped automatically.

2. SEO and Metadata

Since documentation is public, proper metadata is crucial for search engine indexing and user clarity.

---
title: Page Title (Human Readable)
description: A short, keyword-rich summary for search results (aim for 150-160 characters).
---
  • Title: Use clear, descriptive titles (e.g., "Connecting your Garmin" instead of just "Garmin").
  • Description: This becomes the <meta name="description"> and is visible in the documentation index.

3. Content Guidelines

Headers and Hierarchy

  • No H1 in Markdown: The layout automatically uses the title from frontmatter as the H1.
  • Start with H2: Your content should begin with a ## Heading.
  • Logical Flow: Use H3 (###) for sub-sections. Avoid going deeper than H4 for readability.

Voice and Tone

  • Athlete Docs: Empathetic, encouraging, and clear.
    • Use Active Voice: "Connect your watch" instead of "The watch can be connected."
    • Avoid Jargon: Explain terms like "TSS" or "V02 Max" in plain language.
    • UI Elements: Use bold for buttons or menu items (e.g., "Click Save Changes").
  • Developer Docs: Technical, precise, and example-driven. Use "Code-First" explanations.

Advanced Formatting (MDC)

We use Nuxt Content (MDC) components to enhance readability:

  • Alerts: Use for tips, warnings, or notes. 
    ::alert{type="info"}
Tip: You can sync multiple devices to one account.
::
  • Keyboard Shortcuts: Use <kbd>K</kbd> for key combinations.
  • Code Blocks: Always specify the language:
    • ```bash for CLI.
    • ```typescript for code.
    • ```http for API examples.

4. Media and Images

Store images in /public/media/docs/.

  • Naming: Use kebab-case related to the feature (e.g., strava-auth-step-1.webp).
  • Format: Prefer .webp for better performance.
  • Alt Text: Always include descriptive alt text for accessibility.
![Connecting Strava](/media/docs/strava-auth-step-1.webp)

5. New Page Template

Copy and paste this template when creating a new documentation file:

---
title: Page Name
description: A concise, SEO-friendly description of the topic.
---

## Overview

Briefly explain what the user will achieve with this guide.

## Procedures

1. **Step One**: Actionable instruction.
2. **Step Two**: Actionable instruction.

::alert{type="success"}
Success: You are now synced!
::

## Troubleshooting

Common issues and their solutions.
Back to Index