|
| 1 | +# Documentation style guide |
| 2 | + |
| 3 | +A short reference for writers and reviewers. Goal: keep voice, naming |
| 4 | +and examples consistent across every page on this site. |
| 5 | + |
| 6 | +## Product naming |
| 7 | + |
| 8 | +| Context | Use | Don't use | |
| 9 | +|---|---|---| |
| 10 | +| Prose, headings, marketing | **Docker Agent** (two words, both capitalised — the proper name of the product) | docker-agent, Docker-Agent, docker agent (in prose) | |
| 11 | +| The CLI command | `docker agent` (lower-case, two words, in monospace) | `docker-agent`, `Docker Agent run` | |
| 12 | +| The repository / module path | `docker/docker-agent` | docker/Docker-Agent | |
| 13 | +| Internal identifiers / package names | as defined in code (e.g. `cagent`) — never invent new spellings in prose | mixing internal identifiers into user-facing copy | |
| 14 | + |
| 15 | +A simple rule of thumb: |
| 16 | +- **Talking about the product?** → "Docker Agent" |
| 17 | +- **Showing a command the user types?** → `docker agent run agent.yaml` |
| 18 | + |
| 19 | +## Voice |
| 20 | + |
| 21 | +- Address the reader as **you**, not "we" or "the user". |
| 22 | +- Prefer present tense and active voice ("the agent reads files", |
| 23 | + not "files will be read by the agent"). |
| 24 | +- Keep sentences short. Two short sentences usually beat one compound |
| 25 | + one. |
| 26 | +- Avoid "simply", "just", "easily" — they're rarely accurate and |
| 27 | + often condescending. |
| 28 | + |
| 29 | +## Code samples |
| 30 | + |
| 31 | +- All shell prompts use `$ ` (dollar + space) and the command on the |
| 32 | + same line. Output, when shown, has no prompt. |
| 33 | +- YAML/HCL examples should be runnable as-is when reasonable, or end |
| 34 | + in `# ...` to make truncation explicit. |
| 35 | +- The canonical example agent uses `model: anthropic/claude-sonnet-4-5`. |
| 36 | + Use a different model only when the example is *about* that model. |
| 37 | +- File names in prose are in `monospace` (`agent.yaml`, not "agent.yaml"). |
| 38 | + |
| 39 | +## Callouts |
| 40 | + |
| 41 | +Use the existing pattern; the new visual style does the rest: |
| 42 | + |
| 43 | +```markdown |
| 44 | +<div class="callout callout-tip" markdown="1"> |
| 45 | +<div class="callout-title">When to use it</div> |
| 46 | + <p>Body text.</p> |
| 47 | +</div> |
| 48 | +``` |
| 49 | + |
| 50 | +- `callout-info` — neutral context |
| 51 | +- `callout-tip` — positive, "consider this" |
| 52 | +- `callout-warning` — caution, breaking, security |
| 53 | + |
| 54 | +Don't prefix the title with an emoji — the icon badge already provides |
| 55 | +one. |
| 56 | + |
| 57 | +## Glossary one-liners |
| 58 | + |
| 59 | +When a page first introduces a term, link to its concept page or use |
| 60 | +one of these standard one-liners: |
| 61 | + |
| 62 | +- **Agent** — an LLM with instructions, tools, and (optionally) |
| 63 | + sub-agents, defined in YAML or HCL. |
| 64 | +- **Toolset** — a group of related tools the agent can call (e.g. |
| 65 | + `filesystem`, `shell`, `mcp`). |
| 66 | +- **MCP** — Model Context Protocol, an open standard for tool servers. |
| 67 | +- **A2A** — Agent-to-Agent protocol, used to talk to other agents |
| 68 | + over HTTP. |
| 69 | +- **TUI** — Terminal User Interface, the default interactive front end |
| 70 | + Docker Agent ships with. |
| 71 | +- **OCI** — Open Container Initiative; the same registry format used |
| 72 | + for Docker images. Docker Agent reuses it for sharing agents. |
0 commit comments