--- name: documentation description: Documentation Brief description for SEO and navigation --- ### 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'; ```bash npm install package ``` <\/TabItem> ```bash yarn add package ``` <\/TabItem> <\/Tabs> ``` ### Cards Use cards for navigation or highlighting multiple options: ```markdown import { Card, CardGrid } from '@astrojs\/starlight\/components'; Quick introduction to the basics. <\/Card> 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