📝 Documentation Style Guide

Short, minimal rules for writing docs that are easy to scan by humans and predictable for coding agents.

Core Principles

  • Minimal: Short paragraphs (1–3 sentences). Prefer lists over prose.

  • Predictable: Stable section names, consistent headings, tested commands.

  • Scannable: H2 with emojis; use code blocks, short admonitions, and sparse grids.

  • Agent-friendly: Include commands, paths, and config near the top; use anchors and cross-refs.

Page Template

Use this template as the default structure.

---
summary: One-line purpose
tags: [topic, subtopic]
updated: YYYY-MM-DD
audience: [dev, agent]
---

# Page Title

One short intro sentence.

```{admonition} Quick Reference
:class: tip
- Command: `uv run …`
- Path: `src/tatbot/...`
- Config: `src/conf/...`
```

## ⚡ Quick Start
- Step 1 …
- Step 2 …

## 🛠️ Configuration
```yaml
# Prefer literalinclude in real docs
key: value
```

## Usage
```bash
uv run python -m tatbot.viz.teleop --enable-robot
```

## Troubleshooting
- Symptom → Fix
- Error → Cause → Verify command

## Reference
- :doc:`Related Topic <nodes>`
- :ref:`Internal Anchor`

Headings

  • H1: Page title only (one per page). Must include emoji for visual appeal and topic identification.

  • H2: Major sections, no emojis. Use clear, descriptive section names.

  • H3: Subsections, no emoji. Avoid H4+; prefer lists or additional pages.

Exception: The root index page (docs/index.md) may use emojis in H2 headings for visual hierarchy and navigation aid.

Visual Elements

  • Grids: Use only for overviews/landing pages. Keep items concise.

  • Tabs: Use for true alternatives (e.g., Method A vs B). Don’t tab trivial variations.

  • Admonitions: Prefer built-ins: {tip}, {note}, {warning}, {important}. Keep content short.

Examples of fenced content inside examples must use four backticks:

```{admonition} Prerequisites
:class: important
- Installed: `uv`, Python 3.11
```

Agent Optimization

  • Put a “Quick Reference” block near the top (commands, paths, config).

  • Use consistent H2 anchors: “Quick Start”, “Configuration”, “Usage”, “Troubleshooting”, “Reference” (no emojis).

  • Prefer structured lists over long paragraphs; avoid screenshots of text.

  • Include real paths and commands; minimize interactive prompts and long outputs.

Linking

  • Prefer :doc: and :ref: for internal links; avoid raw file/line mentions.

  • Use literalinclude to pull config/code from src/ or config/ to prevent drift.

  • Use node substitutions defined in conf.py (e.g., {{eek}}) for consistent labels.

Checklist

  • H1 once; H2 without emojis (except root index); H3 only as needed.

  • Intro + Quick Reference present and accurate.

  • Commands tested; code blocks have language tags.

  • Links resolve; cross-refs use :doc:/:ref:.

  • Page stays focused (< ~800 words). Split if needed.

Do / Don’t

  • Do: Lists, short admonitions, stable anchors, literalinclude, minimal grids.

  • Don’t: Emoji on H2/H3+ (except root index), decorative grids for simple lists, long terminal dumps, duplicate admonition styles.

Implementation Notes

  • Theme: Furo with copy buttons and sphinx_design.

  • MyST: colon_fence, substitution, anchors up to H3 as configured in conf.py.

  • Keep substitutions, CSS, and theme tweaks centralized (see docs/conf.py, _static/tatbot.css).