diff --git a/README.md b/README.md index fd2d26b..4102a4c 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,103 @@ -# Doc Writer Knowledgebase for Coder.com +# Coder AI Knowledge Base -## Suggested Prompt for Claude Code and ChatGPT +## Purpose -To ensure consistent and context-aware assistance from ChatGPT or Claude Code, use the following prompt when starting a session: +This repository provides AI assistants with instant Coder expertise without requiring formal training on the codebase. Upload these files to give any AI comprehensive knowledge about Coder's architecture, commands, patterns, and documentation standards. -```md -You are assisting with technical documentation for the open source Coder project (https://github.com/coder/coder). +The official Coder documentation at https://coder.com/docs is the single source of truth. This knowledge base provides AI-optimized knowledge that complements the official docs with mental models, patterns, and standards. -You should follow the rules and preferences outlined in these files in the `shared-docs-kb` directory: +## Quick Start -1. style-guide.md (formatting and tone rules) -2. architecture-notes.md (high-level architecture of the product) -3. templates/doc-template.md (content structure scaffolds) -4. templates/snippet-library.md (reusable CLI/YAML/config blocks) -5. ai-project-notes.md (recent work log and in-progress ideas) -6. claude-code-config.md (rules for Claude's behavior) +When starting an AI session, upload relevant files from this repository and use this prompt: -You are not responsible for copyediting or tone unless asked; focus on: +``` +You are now an expert on Coder, the open-source platform for provisioning remote development environments. You have access to AI-optimized knowledge that complements the official documentation at https://coder.com/docs. + +Your expertise includes: +- Coder architecture and internal workings +- Documentation standards and markdown conventions +- Common patterns and troubleshooting approaches +- Community best practices and real-world usage +- Cross-cutting knowledge that spans multiple doc sections + +When helping with documentation tasks: +1. Follow the documentation standards strictly for consistency +2. Reference official docs at https://coder.com/docs as the authoritative source +3. Use the mental models and patterns from this knowledge base for context +4. Suggest improvements to both official docs and this knowledge base when gaps are identified +5. Never use emojis in headings or list items +6. Always maintain technical accuracy and follow established style conventions + +Contribute updates to both official docs (primary) and this knowledge base (auxiliary) when gaps are identified. +``` -1. technical accuracy (based on the codebase and documented architecture) -2. adherence to file placement and structure -3. verifying commands, parameters, and file references -4. following our markdown and terminology conventions +--- -Do not use emojis in headings or list items. Do not flatter me. Use relative paths in links. If you're unsure, ask before making assumptions. +## Knowledge Base Structure -When an issue arises, before you attempt to fix the issue, consult the Coder codebase for examples of potential fixes or for other examples that might work towards the same purpose. +### Documentation Standards +**Essential for consistent contributions** +- `style-guide.md` - Markdown formatting, tone, and conventions +- `templates/doc-template.md` - Content structure scaffolds +- `templates/snippet-library.md` - Reusable CLI/YAML/config blocks -Let me know when you have read the general notes, and I will tell you what we're working on. -``` +### Architecture and Mental Models +**High-level understanding of how Coder works** +- `architecture-notes.md` - Technical understanding of Coder systems +- `repo-navigation.md` - Guide to Coder's public repositories -You can paste this prompt directly into Claude Code or ChatGPT (Pro) and then upload or paste relevant files as needed. +### AI Integration and Workflows +**Optimized for AI assistance** +- `integration/claude-code-config.md` - Claude-specific behavior guidelines +- `integration/chatgpt-config.md` - ChatGPT workflow configuration +- `ai-project-notes.md` - Session logs and accumulated learnings + +### Reference and Support +**Quick access to common information** +- `cli-reference.md` - CLI command documentation and examples +- `common-questions.md` - FAQ with answers and documentation status +- `documentation-gaps.md` - Tracked missing or incomplete documentation --- -Welcome to your personal and collaborative documentation-sidecar knowledgebase. This repo is intended to assist and streamline your work on [Coder documentation](https://github.com/coder/coder), especially in collaboration with AI tools like ChatGPT and Claude Code. +## Use Cases -This directory β€” `shared-docs-kb/` β€” is meant to live alongside the `coder/` and `coder.com/` repositories within your local workspace. +### Documentation Writing +1. Upload `style-guide.md` for formatting consistency +2. Upload `architecture-notes.md` for technical context +3. Upload relevant templates for structure guidance +4. AI produces consistent, accurate documentation ---- +### User Support +1. Upload `common-questions.md` for known issues and solutions +2. Upload `cli-reference.md` for command syntax +3. Upload `architecture-notes.md` for system understanding +4. AI provides knowledgeable, consistent help -## Purpose +### Code Review +1. Upload `architecture-notes.md` for design context +2. Upload `style-guide.md` for consistency checks +3. AI reviews code against established patterns -This repo acts as a **persistent memory store** for markdown/style preferences, architectural understanding, and AI-generated notes. It is designed to: +--- -1. Serve as a **sidecar knowledgebase** for the primary maintainer (Edward Angert) +## Key Principles -1. Act as an **AI Subject Matter Expert (AI-SME)** for use in LLM workflows +### Complement, Don't Duplicate +- Official docs at https://coder.com/docs are the authoritative source +- This knowledge base provides context, patterns, and AI optimization +- When gaps are found, contribute to both official docs and this knowledge base -1. Be a **shared workspace** for coworkers to contribute insights, style clarifications, architecture notes, and documentation patterns +### Documentation Standards First +- Consistency in style, tone, and formatting is critical +- AI should follow established conventions strictly +- All contributions should meet quality standards +- Never use emojis in headings or list items -The goal is to reduce context-switching, enforce style and consistency, and enable teammates or AI to step in seamlessly. +### Shared Resource +- Multiple teams can use this for different purposes +- Contributions welcome from all Coder community members +- Maintain broad utility while staying focused --- diff --git a/ai-project-notes.md b/ai-project-notes.md index 6445b3a..2e0e8fe 100644 --- a/ai-project-notes.md +++ b/ai-project-notes.md @@ -54,6 +54,45 @@ This is a running log of notes, observations, decisions, and refinements related --- +## [Session ID: 2025-01-15-004] Combined AI Knowledge Base Approach +**Human Contributor**: User +**AI Assistant**: Claude (Blink) +**Focus Area**: Repository consolidation and documentation standards + +### Context +- Two separate PRs were created in this session with different approaches +- Need to combine the best of both while maintaining strict documentation standards +- Critical requirement: never use emojis in headings or list items +- Focus on AI-optimized knowledge that complements official docs + +### Discoveries +- Repository should provide instant AI expertise without formal training +- Documentation standards are critical for consistency +- Official docs at https://coder.com/docs must remain single source of truth +- This knowledge base should complement, not duplicate official documentation +- Emoji usage in headings is a major concern that must be prevented + +### Decisions Made +- Combined both PR approaches into single coherent system +- Enhanced style guide with critical rules section emphasizing no emojis +- Maintained existing valuable content while improving structure +- Created clear use cases for different scenarios (documentation writing, user support, code review) +- Established principles: complement don't duplicate, documentation standards first, shared resource + +### Memory Updates +- README.md: Completely rewritten to combine both approaches +- style-guide.md: Enhanced with critical rules and AI guidelines +- documentation-standards/: New directory with enhanced style guide +- Structure: Organized around documentation standards, architecture, AI integration, and reference + +### Next Steps +- Close the two separate PRs and create single combined PR +- Ensure all files follow the documentation standards strictly +- Test the knowledge base with AI assistants to verify effectiveness +- Add remaining files for patterns and community knowledge as needed + +--- + ## [TEMPLATE] ## [YYYY-MM-DD] Topic or Focus @@ -64,4 +103,4 @@ This is a running log of notes, observations, decisions, and refinements related --- -_Last updated: 2025-05-06_ +_Last updated: 2025-01-15_ diff --git a/documentation-standards/style-guide-enhanced.md b/documentation-standards/style-guide-enhanced.md new file mode 100644 index 0000000..8e0bbc6 --- /dev/null +++ b/documentation-standards/style-guide-enhanced.md @@ -0,0 +1,294 @@ +# Coder Documentation Style Guide + +This guide ensures consistency across all Coder documentation. AI assistants should follow these standards strictly when creating or editing documentation. + +--- + +## Critical Rules + +### No Emojis in Headings or List Items +**This is non-negotiable** +- Never use emojis in headings: `# Getting Started` not `# πŸš€ Getting Started` +- Never use emojis to start list items: `- Install Coder` not `- πŸ”§ Install Coder` +- Emojis may be used sparingly in body text for emphasis, but avoid in structural elements + +### Markdown Formatting +- Use `#` for page titles (H1) - only one per document +- Use `##` for main sections (H2) +- Use `###` for subsections (H3) +- Avoid going deeper than `####` (H4) +- Use sentence case: "Creating templates" not "Creating Templates" + +### Code Blocks +- Always specify language: ````bash`, `json`, `yaml`, `hcl`, `go` +- Use `bash` for command-line examples +- Use `console` for command output +- Include comments for complex examples + +```bash +# Create a new template from GitHub +coder templates create my-template https://github.com/user/repo + +# Create from specific directory +coder templates create my-template https://github.com/user/repo --directory examples/docker +``` + +### Lists +- Use `-` for unordered lists (not `*` or `+`) +- Use `1.` for ordered lists +- Keep list items concise +- Use parallel structure (all items same format) + +### Links +- Use relative paths for internal links: `../admin/configure.md` +- Use descriptive link text: `[template creation guide](../templates/creating.md)` +- Avoid "click here" or "read more" +- Link to specific sections when helpful: `[SSH configuration](../user-guides/ssh.md#configuration)` + +### Inline Code +- Use backticks for: + - Commands: `coder create` + - File names: `main.tf` + - Environment variables: `CODER_ACCESS_URL` + - Code snippets: `resource "coder_agent"` + - UI elements: **Settings** > **Templates** + +--- + +## Content Structure + +### Page Organization +1. **Title** (H1) +2. **Brief description** of what this page covers +3. **Prerequisites** (if any) +4. **Main content** with clear sections +5. **Related topics** or next steps + +### Section Flow +- Start with overview/context +- Provide step-by-step instructions +- Include working examples +- Address common issues +- Link to related information + +### Examples +- Always provide working, tested examples +- Include both basic and advanced usage +- Show expected output when helpful +- Explain what each example demonstrates + +--- + +## Tone and Voice + +### Writing Style +- **Direct and clear**: Get to the point quickly +- **Instructional**: Focus on what the user should do +- **Helpful**: Anticipate questions and provide context +- **Professional**: Avoid casual language or jokes + +### Audience +- **Primary**: Developers and system administrators +- **Assume**: Basic familiarity with development tools +- **Don't assume**: Deep knowledge of Coder internals + +### Language +- Use active voice: "Create a template" not "A template can be created" +- Use imperative mood for instructions: "Run the command" not "You should run" +- Be specific: "Set CPU to 2 cores" not "Increase CPU" +- Avoid filler words: "simply", "just", "easily" + +--- + +## Terminology + +### Coder-Specific Terms +- **workspace** (not "environment" or "container") +- **template** (not "config" or "definition") +- **agent** (not "runner" or "daemon") +- **provisioner** (not "builder" or "executor") +- **deployment** (for Coder server installation) + +### Consistent Usage +- **Coder** (not "coder" unless in code) +- **VS Code** (not "VSCode" or "Visual Studio Code") +- **GitHub** (not "Github") +- **Terraform** (not "terraform" unless in code) +- **Kubernetes** (not "K8s" in documentation) + +### Technical Terms +- Define terms on first use +- Link to glossary when available +- Use consistent definitions across docs + +--- + +## Code Examples + +### Command-Line Examples +```bash +# Good: Include context and expected outcome +coder templates create docker-template ./docker-template +# Output: Template "docker-template" created successfully + +# Show common variations +coder templates create docker-template https://github.com/coder/coder --directory examples/templates/docker +``` + +### Configuration Examples +```hcl +# Good: Include comments explaining key parts +resource "coder_agent" "main" { + # Agent runs on the workspace instance + arch = data.coder_provisioner.me.arch + os = data.coder_provisioner.me.os + + # Startup script configures the environment + startup_script = """ + #!/bin/bash + # Install development tools + sudo apt-get update && sudo apt-get install -y git + """ +} +``` + +### Error Examples +```console +# Show actual error messages users might see +Error: Template validation failed + on main.tf line 15: + 15: resource "coder_agent" "main" { + +Agent resource requires 'arch' and 'os' parameters. +``` + +--- + +## Images and Media + +### Screenshots +- Use consistent browser/OS when possible +- Highlight relevant UI elements +- Keep images up-to-date with current UI +- Store in `/docs/images/` directory +- Use descriptive filenames: `template-creation-form.png` + +### Image References +```markdown +![Template creation form](../images/template-creation-form.png) +``` + +### Alt Text +- Describe what the image shows +- Include relevant text from the image +- Keep concise but descriptive + +--- + +## Admonitions and Callouts + +### GitHub-Flavored Markdown +```markdown +> [!NOTE] +> This feature requires Coder v2.1.0 or later. + +> [!WARNING] +> Deleting a template will stop all workspaces using that template. + +> [!TIP] +> Use `coder templates pull` to update templates from their source. +``` + +### When to Use +- **NOTE**: Additional context or clarification +- **WARNING**: Potential data loss or breaking changes +- **TIP**: Helpful suggestions or best practices +- **IMPORTANT**: Critical information that affects functionality + +--- + +## Quality Checklist + +Before publishing documentation: + +### Content +- [ ] Information is accurate and tested +- [ ] Examples work as written +- [ ] Links are valid and point to correct locations +- [ ] Prerequisites are clearly stated +- [ ] Common issues are addressed + +### Style +- [ ] Follows markdown formatting rules +- [ ] Uses consistent terminology +- [ ] Maintains appropriate tone +- [ ] **No emojis in headings or list items** +- [ ] Code blocks have language specified + +### Structure +- [ ] Clear headings and organization +- [ ] Logical flow from simple to complex +- [ ] Related topics are linked +- [ ] Page fits within overall doc structure + +### Accessibility +- [ ] Images have descriptive alt text +- [ ] Links have meaningful text +- [ ] Content is scannable with headings +- [ ] Code examples are readable + +--- + +## AI Assistant Guidelines + +When using AI to create or edit documentation: + +1. **Always reference this style guide** before writing +2. **Follow formatting rules strictly** for consistency +3. **Use established terminology** from this guide +4. **Include working examples** that have been tested +5. **Maintain the appropriate tone** for technical documentation +6. **Check against the quality checklist** before submitting +7. **Never use emojis in headings or list items** + +### Common AI Pitfalls to Avoid +- Adding emojis to headings or lists +- Using inconsistent terminology +- Creating examples that haven't been tested +- Writing in overly casual tone +- Forgetting to specify code block languages +- Using "click here" or vague link text + +--- + +## Interactive Q&A Guidelines + +When AI assistants answer questions about Coder: + +### Response Structure +1. **Direct answer** with working command or solution +2. **Reference to official docs** at https://coder.com/docs +3. **Additional context** when helpful +4. **Documentation gap identification** if information is missing + +### Example Response Format +``` +To copy a template from a GitHub repo, use: + +`coder templates create my-template https://github.com/user/repo` + +For complete documentation on template creation, see: +https://coder.com/docs/templates/creating-templates + +I notice the official docs could use clearer GitHub examples. Would you like me to help create a contribution to improve this section? +``` + +### Gap Detection and Contribution +- Always check if information exists in official docs +- Offer to contribute missing information to official documentation +- Update this knowledge base with new patterns and insights +- Track common questions that aren't well documented + +--- + +_This style guide should be updated as documentation standards evolve._ \ No newline at end of file diff --git a/style-guide.md b/style-guide.md index f826c48..8e0bbc6 100644 --- a/style-guide.md +++ b/style-guide.md @@ -1,105 +1,294 @@ # Coder Documentation Style Guide -This guide defines the preferred conventions, formatting patterns, and stylistic choices for writing and editing documentation in `../coder/docs/`. It’s used by both human collaborators and AI assistants. +This guide ensures consistency across all Coder documentation. AI assistants should follow these standards strictly when creating or editing documentation. --- -## Tone and Voice +## Critical Rules -- Use a **direct, clear, and instructional tone** -- Assume a **developer or technical admin** as your reader -- Avoid jargon unless necessary β€” explain new terms when introduced -- Prioritize **user actions** and outcomes +### No Emojis in Headings or List Items +**This is non-negotiable** +- Never use emojis in headings: `# Getting Started` not `# πŸš€ Getting Started` +- Never use emojis to start list items: `- Install Coder` not `- πŸ”§ Install Coder` +- Emojis may be used sparingly in body text for emphasis, but avoid in structural elements ---- +### Markdown Formatting +- Use `#` for page titles (H1) - only one per document +- Use `##` for main sections (H2) +- Use `###` for subsections (H3) +- Avoid going deeper than `####` (H4) +- Use sentence case: "Creating templates" not "Creating Templates" -## Markdown Formatting Rules +### Code Blocks +- Always specify language: ````bash`, `json`, `yaml`, `hcl`, `go` +- Use `bash` for command-line examples +- Use `console` for command output +- Include comments for complex examples -### Headings -- Use `#`, `##`, `###` β€” avoid going deeper than `####` -- Top-level headings (H1) should only appear once per file -- Prefer heading structure over bold for organization -- **Do not use emojis in headings** +```bash +# Create a new template from GitHub +coder templates create my-template https://github.com/user/repo + +# Create from specific directory +coder templates create my-template https://github.com/user/repo --directory examples/docker +``` ### Lists -- Always use `1.` for **ordered lists** -- Use `-` for **unordered lists** -- Do not use emojis to start list items -- Keep list items as short as possible β€” use full sentences only when needed +- Use `-` for unordered lists (not `*` or `+`) +- Use `1.` for ordered lists +- Keep list items concise +- Use parallel structure (all items same format) -### Code and Inline Elements +### Links +- Use relative paths for internal links: `../admin/configure.md` +- Use descriptive link text: `[template creation guide](../templates/creating.md)` +- Avoid "click here" or "read more" +- Link to specific sections when helpful: `[SSH configuration](../user-guides/ssh.md#configuration)` + +### Inline Code - Use backticks for: - - File names (`manifest.json`) - - CLI flags (`--debug`) - - Inline code (`coder templates create`) - - Environment variables (`CODER_AGENT_LOG`) -- Include a language tag on all code blocks (e.g., `bash`, `json`, `md`) -- Examples: - ```bash - coder templates create --name dev --template ./terraform - ``` + - Commands: `coder create` + - File names: `main.tf` + - Environment variables: `CODER_ACCESS_URL` + - Code snippets: `resource "coder_agent"` + - UI elements: **Settings** > **Templates** -### Links -- Use relative paths for internal links (e.g., `../admin/configure-firewall.md`) -- Avoid linking directly to headings β€” unless persistent -- Use link text that describes the destination purpose +--- + +## Content Structure + +### Page Organization +1. **Title** (H1) +2. **Brief description** of what this page covers +3. **Prerequisites** (if any) +4. **Main content** with clear sections +5. **Related topics** or next steps + +### Section Flow +- Start with overview/context +- Provide step-by-step instructions +- Include working examples +- Address common issues +- Link to related information + +### Examples +- Always provide working, tested examples +- Include both basic and advanced usage +- Show expected output when helpful +- Explain what each example demonstrates + +--- + +## Tone and Voice + +### Writing Style +- **Direct and clear**: Get to the point quickly +- **Instructional**: Focus on what the user should do +- **Helpful**: Anticipate questions and provide context +- **Professional**: Avoid casual language or jokes + +### Audience +- **Primary**: Developers and system administrators +- **Assume**: Basic familiarity with development tools +- **Don't assume**: Deep knowledge of Coder internals + +### Language +- Use active voice: "Create a template" not "A template can be created" +- Use imperative mood for instructions: "Run the command" not "You should run" +- Be specific: "Set CPU to 2 cores" not "Increase CPU" +- Avoid filler words: "simply", "just", "easily" + +--- + +## Terminology + +### Coder-Specific Terms +- **workspace** (not "environment" or "container") +- **template** (not "config" or "definition") +- **agent** (not "runner" or "daemon") +- **provisioner** (not "builder" or "executor") +- **deployment** (for Coder server installation) + +### Consistent Usage +- **Coder** (not "coder" unless in code) +- **VS Code** (not "VSCode" or "Visual Studio Code") +- **GitHub** (not "Github") +- **Terraform** (not "terraform" unless in code) +- **Kubernetes** (not "K8s" in documentation) + +### Technical Terms +- Define terms on first use +- Link to glossary when available +- Use consistent definitions across docs + +--- + +## Code Examples + +### Command-Line Examples +```bash +# Good: Include context and expected outcome +coder templates create docker-template ./docker-template +# Output: Template "docker-template" created successfully + +# Show common variations +coder templates create docker-template https://github.com/coder/coder --directory examples/templates/docker +``` + +### Configuration Examples +```hcl +# Good: Include comments explaining key parts +resource "coder_agent" "main" { + # Agent runs on the workspace instance + arch = data.coder_provisioner.me.arch + os = data.coder_provisioner.me.os + + # Startup script configures the environment + startup_script = """ + #!/bin/bash + # Install development tools + sudo apt-get update && sudo apt-get install -y git + """ +} +``` + +### Error Examples +```console +# Show actual error messages users might see +Error: Template validation failed + on main.tf line 15: + 15: resource "coder_agent" "main" { + +Agent resource requires 'arch' and 'os' parameters. +``` --- -## Visual Standards +## Images and Media + +### Screenshots +- Use consistent browser/OS when possible +- Highlight relevant UI elements +- Keep images up-to-date with current UI +- Store in `/docs/images/` directory +- Use descriptive filenames: `template-creation-form.png` -### Alerts and Admonitions -- Use GitHub-flavored Markdown extensions: - ```md - > [!NOTE] - > This feature requires version 2.1.0 or later. - ``` +### Image References +```markdown +![Template creation form](../images/template-creation-form.png) +``` -### Images -- Store images in `../coder/docs/images/` -- Reference with relative paths and use ``: - ```md - Template setup UI - ``` -- Don’t use percent widths (`100%`) β€” use pixel widths only +### Alt Text +- Describe what the image shows +- Include relevant text from the image +- Keep concise but descriptive --- -## Terminology Consistency +## Admonitions and Callouts -| Preferred Term | Avoid | -|----------------------|---------------------------| -| workspace | dev environment, container | -| template | config, environment | -| admin | administrator, ops | -| provisioner | builder, terraform system | -| agent | runtime, runner | +### GitHub-Flavored Markdown +```markdown +> [!NOTE] +> This feature requires Coder v2.1.0 or later. -Refer to: -- `.markdownlint.jsonc` for rule enforcement -- [Google style guide](https://developers.google.com/style/) -- [GitLab doc style](https://docs.gitlab.com/ee/development/documentation/styleguide/) +> [!WARNING] +> Deleting a template will stop all workspaces using that template. + +> [!TIP] +> Use `coder templates pull` to update templates from their source. +``` + +### When to Use +- **NOTE**: Additional context or clarification +- **WARNING**: Potential data loss or breaking changes +- **TIP**: Helpful suggestions or best practices +- **IMPORTANT**: Critical information that affects functionality --- -## Document Hygiene +## Quality Checklist + +Before publishing documentation: + +### Content +- [ ] Information is accurate and tested +- [ ] Examples work as written +- [ ] Links are valid and point to correct locations +- [ ] Prerequisites are clearly stated +- [ ] Common issues are addressed + +### Style +- [ ] Follows markdown formatting rules +- [ ] Uses consistent terminology +- [ ] Maintains appropriate tone +- [ ] **No emojis in headings or list items** +- [ ] Code blocks have language specified + +### Structure +- [ ] Clear headings and organization +- [ ] Logical flow from simple to complex +- [ ] Related topics are linked +- [ ] Page fits within overall doc structure -- Avoid TODOs or placeholders in merged docs -- Update `manifest.json` whenever you add/move docs -- Check anchor links if you rename headings or move files -- Run: - ```bash - make lint - make fmt - ``` +### Accessibility +- [ ] Images have descriptive alt text +- [ ] Links have meaningful text +- [ ] Content is scannable with headings +- [ ] Code examples are readable --- -## AI Guidance Notes +## AI Assistant Guidelines + +When using AI to create or edit documentation: + +1. **Always reference this style guide** before writing +2. **Follow formatting rules strictly** for consistency +3. **Use established terminology** from this guide +4. **Include working examples** that have been tested +5. **Maintain the appropriate tone** for technical documentation +6. **Check against the quality checklist** before submitting +7. **Never use emojis in headings or list items** + +### Common AI Pitfalls to Avoid +- Adding emojis to headings or lists +- Using inconsistent terminology +- Creating examples that haven't been tested +- Writing in overly casual tone +- Forgetting to specify code block languages +- Using "click here" or vague link text + +--- + +## Interactive Q&A Guidelines + +When AI assistants answer questions about Coder: + +### Response Structure +1. **Direct answer** with working command or solution +2. **Reference to official docs** at https://coder.com/docs +3. **Additional context** when helpful +4. **Documentation gap identification** if information is missing + +### Example Response Format +``` +To copy a template from a GitHub repo, use: + +`coder templates create my-template https://github.com/user/repo` + +For complete documentation on template creation, see: +https://coder.com/docs/templates/creating-templates + +I notice the official docs could use clearer GitHub examples. Would you like me to help create a contribution to improve this section? +``` -When pasting this file into Claude or ChatGPT, include a prompt like: -> β€œUse this style guide to review or generate documentation. Focus on formatting, clarity, and tone. Don’t override structure unless requested.” +### Gap Detection and Contribution +- Always check if information exists in official docs +- Offer to contribute missing information to official documentation +- Update this knowledge base with new patterns and insights +- Track common questions that aren't well documented --- -_Last updated: 2025-05-05_ +_This style guide should be updated as documentation standards evolve._ \ No newline at end of file