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
| Section |
Purpose |
| Overview |
What the API does, base URL, versioning |
| Authentication |
How to get and use credentials |
| Rate Limits |
Throttling rules and headers |
| Endpoints |
Per-endpoint details |
| Errors |
Error format and common codes |
| Changelog |
API version history |
User Guide Structure
| Section |
Purpose |
| Introduction |
What, why, for whom |
| Installation |
How to set up |
| Quick Start |
First success in 5 minutes |
| Core Concepts |
Key ideas to understand |
| How-To Guides |
Task-oriented walkthroughs |
| Troubleshooting |
Common issues and fixes |
README Best Practices
| Section |
Required? |
| Project name + description |
✅ Yes |
| Badges (build, version) |
Recommended |
| Quick start / Installation |
✅ Yes |
| Usage examples |
✅ Yes |
| Configuration |
If applicable |
| Contributing |
Recommended |
| License |
✅ Yes |
Docs-as-Code Tools
Static Site Generators
| Tool |
Best For |
Config File |
| MkDocs |
Python projects, simple setup |
mkdocs.yml |
| Docusaurus |
React, versioning, i18n |
docusaurus.config.js |
| Sphinx |
Python autodocs |
conf.py |
| GitBook |
Beautiful docs, non-technical |
book.json |
| VitePress |
Vue projects, fast |
.vitepress/config.js |
API Documentation Tools
| Tool |
Format |
Output |
| OpenAPI/Swagger |
YAML/JSON spec |
Interactive docs |
| Redoc |
OpenAPI |
Static HTML |
| Stoplight |
Design-first |
Portal |
| Postman |
Collections |
Shareable docs |
Writing Patterns
The 4 Cs of Technical Writing
| Principle |
Meaning |
| Clear |
No ambiguity, simple words |
| Concise |
No filler, respect reader's time |
| Correct |
Accurate, tested, up-to-date |
| Complete |
All needed info present |
Code Example Guidelines
| Do |
Don't |
| Show complete, runnable examples |
Partial snippets without context |
| Include error handling |
Happy path only |
| Use realistic data |
foo, bar, test123 |
| Explain non-obvious parts |
Assume reader knows everything |
Common Pitfalls
| Pitfall |
Solution |
| Outdated screenshots |
Automate with Puppeteer/Playwright |
| Broken links |
CI link checking |
| Stale examples |
Tests for code samples |
| Jargon overload |
Glossary + define on first use |
1---2name: api-documentation-43description: Technical documentation, API references, user guides, and docs-as-code workflows.4tier: standard5applyTo: '**/*doc*,**/*api*,**/*readme*,**/*guide*'6currency: 2026-04-227metadata:8 source: https://skillmd.com/skills/fabioc-aloha/api-documentation-49---1011# API Documentation Skill1213> Technical documentation, API references, user guides, and docs-as-code workflows.1415---1617## Documentation Project Scaffolding1819### Recommended Folder Structure2021```text22docs-project/23├── .github/24│ ├── copilot-instructions.md # Docs-specific Alex context25│ └── prompts/26│ └── api-review.prompt.md27├── docs/28│ ├── index.md # Landing page / overview29│ ├── getting-started/30│ │ ├── installation.md31│ │ ├── quick-start.md32│ │ └── configuration.md33│ ├── guides/34│ │ ├── user-guide.md35│ │ └── admin-guide.md36│ ├── api/37│ │ ├── overview.md38│ │ ├── authentication.md39│ │ ├── endpoints/40│ │ │ └── [resource].md41│ │ └── errors.md42│ ├── reference/43│ │ ├── glossary.md44│ │ └── faq.md45│ └── contributing/46│ ├── style-guide.md47│ └── templates.md48├── examples/49│ ├── code-snippets/50│ └── sample-projects/51├── assets/52│ ├── images/53│ └── diagrams/54├── CHANGELOG.md55├── README.md56└── mkdocs.yml # Or docusaurus.config.js57```5859### DOCS-PLAN.md Template6061```markdown62# Documentation Plan: [Product/API Name]6364## Scope65- **Product**: [What are we documenting?]66- **Audience**: [Developers / Admins / End Users]67- **Prerequisites**: [What readers should know]6869## Documentation Types7071| Type | Location | Status |72|------|----------|--------|73| Getting Started | docs/getting-started/ | ⬜ |74| User Guide | docs/guides/user-guide.md | ⬜ |75| API Reference | docs/api/ | ⬜ |76| Examples | examples/ | ⬜ |7778## Style Guidelines79- **Tone**: [Technical but approachable]80- **Person**: [Second person - "you"]81- **Tense**: [Present tense]82- **Code style**: [Language-specific conventions]8384## Quality Checklist85- [ ] All endpoints documented86- [ ] Code examples tested and working87- [ ] Screenshots current88- [ ] Links verified89- [ ] Spelling/grammar checked90```9192### API-ENDPOINT.md Template9394```markdown95# [Endpoint Name]9697[One-line description of what this endpoint does]9899## Request100101\`\`\`http102[METHOD] /api/v1/[resource]103\`\`\`104105### Headers106107| Header | Required | Description |108|--------|----------|-------------|109| Authorization | Yes | Bearer token |110| Content-Type | Yes | application/json |111112### Parameters113114| Parameter | Type | Required | Description |115|-----------|------|----------|-------------|116| id | string | Yes | Resource identifier |117118### Request Body119120\`\`\`json121{122 "field": "value"123}124\`\`\`125126## Response127128### Success (200 OK)129130\`\`\`json131{132 "data": {133 "id": "123",134 "field": "value"135 }136}137\`\`\`138139### Errors140141| Code | Description |142|------|-------------|143| 400 | Invalid request body |144| 401 | Unauthorized |145| 404 | Resource not found |146147## Example148149\`\`\`bash150curl -X GET "https://api.example.com/v1/resource/123" \151 -H "Authorization: Bearer $TOKEN"152\`\`\`153```154155### copilot-instructions.md Template (Documentation Projects)156157```markdown158# [Product Name] Documentation — Context159160## Project Overview161[What product/API this documents, current status]162163## Current Phase164- [x] Structure defined165- [ ] Getting started complete166- [ ] API reference complete167- [ ] Examples tested168169## Key Files170- Docs plan: DOCS-PLAN.md171- Style guide: docs/contributing/style-guide.md172- API overview: docs/api/overview.md173174## Alex Guidance175- **Audience**: [Developers with X experience level]176- **Tone**: Technical but approachable177- Use second person ("you") not third person178- Include working code examples for every endpoint179- Link to related endpoints/concepts180181## Style Rules182- Headings: Sentence case183- Lists: No periods for fragments, periods for sentences184- Code: Include language identifier in fenced blocks185- Links: Use relative paths within docs/186187## Don't188- Don't assume reader knows internal terminology189- Don't document deprecated features without clear warnings190- Don't include placeholder examples — all code must work191```192193### Documentation Project Audit Checklist194195```markdown196## Documentation Project Audit197198### Structure Assessment199- [ ] Clear navigation hierarchy200- [ ] Getting started section exists201- [ ] API reference organized by resource202- [ ] Examples directory with working code203204### Alex-Readiness Assessment205- [ ] copilot-instructions.md exists206- [ ] Audience clearly defined207- [ ] Style guide documented208- [ ] Key files linked209210### Content Assessment211- [ ] All public endpoints documented212- [ ] Authentication explained213- [ ] Error codes listed214- [ ] Code examples in multiple languages (if applicable)215216### Quality Assessment217- [ ] All links valid218- [ ] Code examples tested219- [ ] Screenshots current220- [ ] Consistent formatting221```222223---224225## Documentation Types226227### API Reference Structure228229| Section | Purpose |230|---------|---------|231| **Overview** | What the API does, base URL, versioning |232| **Authentication** | How to get and use credentials |233| **Rate Limits** | Throttling rules and headers |234| **Endpoints** | Per-endpoint details |235| **Errors** | Error format and common codes |236| **Changelog** | API version history |237238### User Guide Structure239240| Section | Purpose |241|---------|---------|242| **Introduction** | What, why, for whom |243| **Installation** | How to set up |244| **Quick Start** | First success in 5 minutes |245| **Core Concepts** | Key ideas to understand |246| **How-To Guides** | Task-oriented walkthroughs |247| **Troubleshooting** | Common issues and fixes |248249### README Best Practices250251| Section | Required? |252|---------|-----------|253| Project name + description | ✅ Yes |254| Badges (build, version) | Recommended |255| Quick start / Installation | ✅ Yes |256| Usage examples | ✅ Yes |257| Configuration | If applicable |258| Contributing | Recommended |259| License | ✅ Yes |260261---262263## Docs-as-Code Tools264265### Static Site Generators266267| Tool | Best For | Config File |268|------|----------|-------------|269| **MkDocs** | Python projects, simple setup | mkdocs.yml |270| **Docusaurus** | React, versioning, i18n | docusaurus.config.js |271| **Sphinx** | Python autodocs | conf.py |272| **GitBook** | Beautiful docs, non-technical | book.json |273| **VitePress** | Vue projects, fast | .vitepress/config.js |274275### API Documentation Tools276277| Tool | Format | Output |278|------|--------|--------|279| **OpenAPI/Swagger** | YAML/JSON spec | Interactive docs |280| **Redoc** | OpenAPI | Static HTML |281| **Stoplight** | Design-first | Portal |282| **Postman** | Collections | Shareable docs |283284---285286## Writing Patterns287288### The 4 Cs of Technical Writing289290| Principle | Meaning |291|-----------|---------|292| **Clear** | No ambiguity, simple words |293| **Concise** | No filler, respect reader's time |294| **Correct** | Accurate, tested, up-to-date |295| **Complete** | All needed info present |296297### Code Example Guidelines298299| Do | Don't |300|----|-------|301| Show complete, runnable examples | Partial snippets without context |302| Include error handling | Happy path only |303| Use realistic data | `foo`, `bar`, `test123` |304| Explain non-obvious parts | Assume reader knows everything |305306### Common Pitfalls307308| Pitfall | Solution |309|---------|----------|310| Outdated screenshots | Automate with Puppeteer/Playwright |311| Broken links | CI link checking |312| Stale examples | Tests for code samples |313| Jargon overload | Glossary + define on first use |314315---