writing-developer-guides

name	writing-developer-guides
description	Structures developer guides for optimal AI agent and human consumption. Use when creating or updating files in contributing/, or when documentation needs to support autonomous coding agents.

Writing Developer Guides

Overview

This skill teaches how to write developer guides that work well for both AI coding agents and human developers. The key insight: AI agents need fast context retrieval, clear decision support, and copy-paste ready patterns.

When to Apply

• Creating a new file in contributing/
• Updating or refactoring an existing guide
• Reviewing guides for completeness
• User asks about documentation structure

Core Principle

Structure for retrieval, not teaching.

Traditional documentation assumes sequential reading. AI agents retrieve specific information based on task context. Every section should be independently useful.

Required Sections (In Order)

Each developer guide must include these sections in this sequence:

1. Title + Overview (2-3 sentences)

# [Topic] Guide

## Overview

[What this guide covers] and [why it matters for this project].

Why this order: AI agents use the overview to determine relevance before reading further.

2. Key Files Table

## Key Files

| Concept       | Location             |
| ------------- | -------------------- |
| Configuration | `src/path/config.ts` |
| Types         | `src/path/types.ts`  |

Why early: Agents need to know WHERE before HOW. This prevents searching.

3. Decision Matrix ("When to Use What")

## When to Use What

| Scenario | Approach | Why       |
| -------- | -------- | --------- |
| Need X   | Use Y    | Because Z |
| Need A   | Use B    | Because C |

Critical for AI: A good decision matrix eliminates 80% of clarifying questions. Agents can pattern-match their current task to the right approach.

4. Core Patterns (Code Examples)

## Core Patterns

### [Pattern Name]

[1-2 sentence context]

```typescript
// Complete, runnable example
// Comments explain WHY, not WHAT
export function example() {
  // This pattern ensures X because Y
  return result;
}
```

**Requirements:**
- Examples must be complete (copy-paste ready)
- Include imports if non-obvious
- Comments explain reasoning, not mechanics

### 5. Anti-Patterns

```markdown
## Anti-Patterns

```typescript
// ❌ NEVER do this
badPattern()  // Causes X problem

// ✅ Do this instead
goodPattern() // Prevents X, ensures Y

**Why essential:** AI agents learn from negative examples. Without anti-patterns, agents may generate common mistakes that "look right" but violate project conventions.

### 6. Step-by-Step Procedures (Optional)

Include when there are procedural tasks (adding X, configuring Y):

```markdown
## Adding a New [Thing]

1. **Create the file**: `path/to/file.ts`
   ```typescript
   // Initial content

2. Register in config: Add to config.ts

   // What to add
   

3. Verify: Run npm run [command] and check for [expected output]

**Key:** Each step should have verification. Agents need to confirm success before proceeding.

### 7. Troubleshooting (Optional but Recommended)

```markdown
## Troubleshooting

### "Error message verbatim"

**Cause**: Why this happens
**Fix**: What to do

### [Symptom description]

**Cause**: Why this happens
**Fix**: What to do

Why this format: AI agents can grep for error messages and find solutions directly.

Writing Guidelines

For AI Agent Consumption

Do	Don't
Use tables for structured data	Use prose for comparisons
Put decision criteria in tables	Bury decisions in paragraphs
Make code examples complete	Show fragments requiring context
Use consistent section headers	Vary section names across guides
Include file paths in examples	Assume agents know locations

For Human Readability

Do	Don't
Keep overview under 3 sentences	Write lengthy introductions
Use bullet points for lists	Use numbered lists unless order matters
Link to related guides	Duplicate content from other guides
Explain "why" in comments	Over-document obvious code

Quality Checklist

Before completing a guide, verify:

• Overview explains what AND why in 2-3 sentences
• Key Files table maps concepts to locations
• Decision matrix covers common scenarios
• All code examples are complete and runnable
• Anti-patterns section exists with ❌/✅ format
• Troubleshooting covers common errors (if applicable)
• Section order matches this skill's template
• No duplicated content from other guides (link instead)

Updating INDEX.md

After creating or modifying a guide:

1. Add/update entry in Guide Coverage Map table
2. Add pattern matching rules (file patterns + keywords)
3. Update Maintenance Tracking with today's date

See contributing/INDEX.md for the format.

References

For the complete section-by-section template with detailed examples, see: reference.md in this skill directory.