API Documentation Skill

API Documentation Skill

Technical documentation, API references, user guides, and docs-as-code workflows.

Documentation Project Scaffolding

Recommended Folder Structure

docs-project/
├── .github/
│   ├── copilot-instructions.md    # Docs-specific Alex context
│   └── prompts/
│       └── api-review.prompt.md
├── docs/
│   ├── index.md                   # Landing page / overview
│   ├── getting-started/
│   │   ├── installation.md
│   │   ├── quick-start.md
│   │   └── configuration.md
│   ├── guides/
│   │   ├── user-guide.md
│   │   └── admin-guide.md
│   ├── api/
│   │   ├── overview.md
│   │   ├── authentication.md
│   │   ├── endpoints/
│   │   │   └── [resource].md
│   │   └── errors.md
│   ├── reference/
│   │   ├── glossary.md
│   │   └── faq.md
│   └── contributing/
│       ├── style-guide.md
│       └── templates.md
├── examples/
│   ├── code-snippets/
│   └── sample-projects/
├── assets/
│   ├── images/
│   └── diagrams/
├── CHANGELOG.md
├── README.md
└── mkdocs.yml                     # Or docusaurus.config.js

DOCS-PLAN.md Template

# Documentation Plan: [Product/API Name]

## Scope
- **Product**: [What are we documenting?]
- **Audience**: [Developers / Admins / End Users]
- **Prerequisites**: [What readers should know]

## Documentation Types

| Type | Location | Status |
|------|----------|--------|
| Getting Started | docs/getting-started/ | ⬜ |
| User Guide | docs/guides/user-guide.md | ⬜ |
| API Reference | docs/api/ | ⬜ |
| Examples | examples/ | ⬜ |

## Style Guidelines
- **Tone**: [Technical but approachable]
- **Person**: [Second person - "you"]
- **Tense**: [Present tense]
- **Code style**: [Language-specific conventions]

## Quality Checklist
- [ ] All endpoints documented
- [ ] Code examples tested and working
- [ ] Screenshots current
- [ ] Links verified
- [ ] Spelling/grammar checked

API-ENDPOINT.md Template

# [Endpoint Name]

[One-line description of what this endpoint does]

## Request

\`\`\`http
[METHOD] /api/v1/[resource]
\`\`\`

### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | Resource identifier |

### Request Body

\`\`\`json
{
  "field": "value"
}
\`\`\`

## Response

### Success (200 OK)

\`\`\`json
{
  "data": {
    "id": "123",
    "field": "value"
  }
}
\`\`\`

### Errors

| Code | Description |
|------|-------------|
| 400 | Invalid request body |
| 401 | Unauthorized |
| 404 | Resource not found |

## Example

\`\`\`bash
curl -X GET "https://api.example.com/v1/resource/123" \
  -H "Authorization: Bearer $TOKEN"
\`\`\`

copilot-instructions.md Template (Documentation Projects)

# [Product Name] Documentation — Context

## Project Overview
[What product/API this documents, current status]

## Current Phase
- [x] Structure defined
- [ ] Getting started complete
- [ ] API reference complete
- [ ] Examples tested

## Key Files
- Docs plan: DOCS-PLAN.md
- Style guide: docs/contributing/style-guide.md
- API overview: docs/api/overview.md

## Alex Guidance
- **Audience**: [Developers with X experience level]
- **Tone**: Technical but approachable
- Use second person ("you") not third person
- Include working code examples for every endpoint
- Link to related endpoints/concepts

## Style Rules
- Headings: Sentence case
- Lists: No periods for fragments, periods for sentences
- Code: Include language identifier in fenced blocks
- Links: Use relative paths within docs/

## Don't
- Don't assume reader knows internal terminology
- Don't document deprecated features without clear warnings
- Don't include placeholder examples — all code must work

Documentation Project Audit Checklist

## Documentation Project Audit

### Structure Assessment
- [ ] Clear navigation hierarchy
- [ ] Getting started section exists
- [ ] API reference organized by resource
- [ ] Examples directory with working code

### Alex-Readiness Assessment
- [ ] copilot-instructions.md exists
- [ ] Audience clearly defined
- [ ] Style guide documented
- [ ] Key files linked

### Content Assessment
- [ ] All public endpoints documented
- [ ] Authentication explained
- [ ] Error codes listed
- [ ] Code examples in multiple languages (if applicable)

### Quality Assessment
- [ ] All links valid
- [ ] Code examples tested
- [ ] Screenshots current
- [ ] Consistent formatting

Documentation Types

API Reference Structure

User Guide Structure

README Best Practices

Docs-as-Code Tools

Static Site Generators

API Documentation Tools

Writing Patterns

The 4 Cs of Technical Writing

Code Example Guidelines

Common Pitfalls

Synapses

High-Strength Connections

• [project-scaffolding] (High, Extends, Bidirectional) — "Documentation project structure"
• [code-quality] (High, Complements, Bidirectional) — "Documented code is quality code"

Medium-Strength Connections

• [creative-writing] (Medium, Complements, Forward) — "Clear writing techniques"
• [git-workflow] (Medium, Uses, Forward) — "Docs-as-code versioning"

Supporting Connections

• [markdown-mastery] (Medium, Uses, Forward) — "Core formatting"
• [appropriate-reliance] (Low, Applies, Forward) — "AI assistance in docs"