github/documentation

Documentation

Documentation lives in docs/, uses GitHub-flavored Markdown, renders with Astro Starlight, and follows Diátaxis.

Diátaxis Framework

Organize documentation into four Diátaxis types:

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