documentation

### Documentation

The documentation for this project is available in the `docs/` directory. It uses GitHub-flavored markdown with Astro Starlight for rendering and follows the Diátaxis framework for systematic documentation.

## Diátaxis Framework

Documentation must be organized into four distinct types, each serving a specific purpose:

### 1. Tutorials (Learning-Oriented)
**Purpose**: Guide beginners through achieving a specific outcome to build confidence.

- Start with what the user will build or achieve
- Provide a clear, step-by-step path from start to finish
- Include concrete examples and working code
- Assume minimal prior knowledge
- Focus on the happy path (avoid edge cases and alternatives)
- End with a working result the user can see and use
- Use imperative mood: "Create a file", "Run the command"

**Avoid**: Explaining concepts in depth, multiple options, troubleshooting

### 2. How-to Guides (Goal-Oriented)
**Purpose**: Show how to solve a specific real-world problem or accomplish a particular task.

- Title format: "How to [accomplish specific goal]"
- Assume the user knows the basics
- Focus on practical steps to solve one problem
- Include necessary context but stay focused
- Show multiple approaches only when genuinely useful
- End when the goal is achieved
- Use imperative mood: "Configure the setting", "Add the following"

**Avoid**: Teaching fundamentals, explaining every detail, being exhaustive

### 3. Reference (Information-Oriented)
**Purpose**: Provide accurate, complete technical descriptions of the system.

- Organized by structure (CLI commands, configuration options, API endpoints)
- Comprehensive and authoritative
- Consistent format across all entries
- Technical accuracy is paramount
- Include all parameters, options, and return values
- Use descriptive mood: "The command accepts", "Returns a string"
- Minimal narrative or explanation

**Avoid**: Instructions, tutorials, opinions on usage

### 4. Explanation (Understanding-Oriented)
**Purpose**: Clarify and illuminate topics to deepen understanding.

- Discuss why things are the way they are
- Explain design decisions and tradeoffs
- Provide context and background
- Connect concepts to help form mental models
- Discuss alternatives and their implications
- Use indicative mood: "This approach provides", "The engine uses"

**Avoid**: Step-by-step instructions, exhaustive reference material

## General Style Guidelines

- **Tone**: Neutral, technical, not promotional
- **Voice**: Avoid "we", "our", "us" (use "the tool", "this command")
- **Headings**: Use markdown heading syntax, not bold text as headings
- **Lists**: Avoid long bullet point lists; prefer prose with structure
- **Code samples**: Minimal and focused; exclude optional fields unless relevant
- **Language tag**: Use `aw` for agentic workflow snippets with YAML frontmatter

**Example workflow code block**:
```aw wrap
on: push
# Your workflow steps here
```

## GitHub-Flavored Markdown Syntax

Documentation files use GitHub-flavored markdown with Astro Starlight for rendering. Key syntax elements:

### Frontmatter
Every documentation page must have frontmatter:
```markdown
title: Page Title
description: Brief description for SEO and navigation
```

### GitHub Alerts
Use GitHub's alert syntax for notes, tips, warnings, and cautions:
```markdown
> [!NOTE]
> Important information the reader should notice.

> [!TIP]
> Helpful advice for the reader.

> [!WARNING]
> Warning about potential issues or pitfalls.

> [!CAUTION]
> Critical warning about dangerous operations.

> [!IMPORTANT]
> Key information users need to know.
```

### Code Blocks
- Use syntax highlighting with language tags
- Add `title` attribute for file names: ` ```yaml title=".github/workflows/example.yml" `
- Use `aw` language for agentic workflow files with YAML frontmatter
- Add `wrap` for line wrapping: ` ```aw wrap `

### Links
- Internal links: Use relative paths between documentation pages
- External links: Open in new tab automatically
- Link text: Use descriptive text, avoid "click here"

### Tabs
Use tabs for showing alternatives (e.g., different languages, platforms):
```markdown
import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="npm">
    ```bash
    npm install package
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add package
    ```
  </TabItem>
</Tabs>
```

### Cards
Use cards for navigation or highlighting multiple options:
```markdown
import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="Getting Started" icon="rocket">
    Quick introduction to the basics.
  </Card>
  <Card title="Advanced Usage" icon="setting">
    Deep dive into advanced features.
  </Card>
</CardGrid>
```

**Remember**: Keep components minimal. Prefer standard markdown when possible.

## Content to Avoid

- "Key Features" sections
- Marketing language or selling points
- Excessive bullet points (prefer structured prose)
- Overly verbose examples with all optional parameters
- Mixing documentation types (e.g., tutorials that become reference)

## Avoiding Documentation Bloat

Documentation bloat reduces clarity and makes content harder to navigate. Common types of bloat include:

### Types of Documentation Bloat

1. **Duplicate content**: Same information repeated in different sections
2. **Excessive bullet points**: Long lists that could be condensed into prose or tables
3. **Redundant examples**: Multiple examples showing the same concept
4. **Verbose descriptions**: Overly wordy explanations that could be more concise
5. **Repetitive structure**: The same "What it does" / "Why it's valuable" pattern overused

### Writing Concise Documentation

When editing documentation, focus on:

**Consolidate bullet points**: 
- Convert long bullet lists into concise prose or tables
- Remove redundant points that say the same thing differently

**Eliminate duplicates**:
- Remove repeated information
- Consolidate similar sections

**Condense verbose text**:
- Make descriptions more direct and concise
- Remove filler words and phrases
- Keep technical accuracy while reducing word count

**Standardize structure**:
- Reduce repetitive "What it does" / "Why it's valuable" patterns
- Use varied, natural language

**Simplify code samples**:
- Remove unnecessary complexity from code examples
- Focus on demonstrating the core concept clearly
- Eliminate boilerplate or setup code unless essential for understanding
- Keep examples minimal yet complete
- Use realistic but simple scenarios

### Example: Before and After

**Before (Bloated)**:
```markdown
### Tool Name
Description of the tool.

- **What it does**: This tool does X, Y, and Z
- **Why it's valuable**: It's valuable because A, B, and C
- **How to use**: You use it by doing steps 1, 2, 3, 4, 5
- **When to use**: Use it when you need X
- **Benefits**: Gets you benefit A, benefit B, benefit C
- **Learn more**: [Link](url)
```

**After (Concise)**:
```markdown
### Tool Name
Description of the tool that does X, Y, and Z to achieve A, B, and C.

Use it when you need X by following steps 1-5. [Learn more](url)
```

### Documentation Quality Guidelines

1. **Preserve meaning**: Never lose important information
2. **Be surgical**: Make precise edits, don't rewrite everything
3. **Maintain tone**: Keep the neutral, technical tone
4. **Test locally**: Verify links and formatting are still correct

## Structure by File Type

- **Getting Started**: Tutorial format
- **How-to Guides**: Goal-oriented, one task per guide
- **CLI Reference**: Reference format, complete command documentation
- **Concepts**: Explanation format, building understanding
- **API Reference**: Reference format, complete API documentation