Guidelines for maintaining and expanding the Container-Compose documentation.
Documentation is structured by intent:
docs/cli/: Reference pages for every subcommand.docs/tutorials/: Step-by-step guides for specific use cases.docs/concepts/: Deep dives into architecture and behavior.
- Terse Imperative Voice: Use "Run the command" instead of "You should run the command".
- Code-First: Lead with examples. Explain the "why" after showing the "how".
- Terminal Annotations: Use
title="terminal"on all shell code blocks. - Feature Linking: Link every mention of a feature to its reference or concept page.
- No Filler: Avoid words like "simply", "obviously", or "just".
docs/cli/<command>.md
---
title: <command>
description: Brief one-sentence summary of what the command does.
---
# <command>
Detailed description of the command's purpose and behavior.
## Synopsis
```bash title="terminal"
container-compose <command> [options] [args]| Option | Shorthand | Description |
|---|---|---|
--flag |
-f |
Description of the flag. |
Description of the example.
container-compose <command>- Don't do X: Explain why X is bad and what to do instead.
### Tutorial Page
`docs/tutorials/<topic>.md`
```markdown
---
title: <topic>
description: What the user will build or achieve in this tutorial.
---
# <topic>
Introduction to the tutorial goals.
## Prerequisites
- List of requirements.
## Step 1: <Action>
Description and code.
```bash title="terminal"
# code
Recap of what was learned.
### Concept Page
`docs/concepts/<topic>.md`
```markdown
---
title: <topic>
description: High-level overview of the concept.
---
# <topic>
Deep dive into the technical details.
## Architecture
How it works under the hood.
## Behavior
Expected outcomes and edge cases.
- Identify the category: Choose between
cli/,tutorials/, orconcepts/. - Apply the template: Copy the relevant skeleton from this page.
- Write the content: Follow the style rules (terse, code-first).
- Link from index: Add your new page to the appropriate section in
docs/index.md.