# Documentation Templates

> Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.

- Skill: `yunaamelia/documentation-templates` (Agent Skill)
- Install (CLI): `npx skillmds add yunaamelia/documentation-templates`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yunaamelia/documentation-templates/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: yunaamelia (https://skillmd.com/u/yunaamelia)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/yunaamelia/documentation-templates

---


# Documentation Templates

> Templates and structure guidelines for common documentation types.

---

## 1. README Structure

### Essential Sections (Priority Order)

| Section               | Purpose               |
| --------------------- | --------------------- |
| **Title + One-liner** | What is this?         |
| **Quick Start**       | Running in <5 min     |
| **Features**          | What can I do?        |
| **Configuration**     | How to customize      |
| **API Reference**     | Link to detailed docs |
| **Contributing**      | How to help           |
| **License**           | Legal                 |

### README Template

```markdown
# Project Name

Brief one-line description.

## Quick Start

[Minimum steps to run]

## Features

- Feature 1
- Feature 2

## Configuration

| Variable | Description | Default |
| -------- | ----------- | ------- |
| PORT     | Server port | 3000    |

## Documentation

- [API Reference](./docs/api.md)
- [Architecture](./docs/architecture.md)

## License

MIT
```

---

## 2. API Documentation Structure

### Per-Endpoint Template

```markdown
## GET /users/:id

Get a user by ID.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |

**Response:**

- 200: User object
- 404: User not found

**Example:**
[Request and response example]
```

---

## 3. Code Comment Guidelines

### JSDoc/TSDoc Template

```typescript
/**
 * Brief description of what the function does.
 *
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws ErrorType - When this error occurs
 *
 * @example
 * const result = functionName(input);
 */
```

### When to Comment

| ✅ Comment           | ❌ Don't Comment       |
| -------------------- | ---------------------- |
| Why (business logic) | What (obvious)         |
| Complex algorithms   | Every line             |
| Non-obvious behavior | Self-explanatory code  |
| API contracts        | Implementation details |

---

## 4. Changelog Template (Keep a Changelog)

```markdown
# Changelog

## [Unreleased]

### Added

- New feature

## [1.0.0] - 2025-01-01

### Added

- Initial release

### Changed

- Updated dependency

### Fixed

- Bug fix
```

---

## 5. Architecture Decision Record (ADR)

```markdown
# ADR-001: [Title]

## Status

Accepted / Deprecated / Superseded

## Context

Why are we making this decision?

## Decision

What did we decide?

## Consequences

What are the trade-offs?
```

---

## 6. AI-Friendly Documentation (2025)

### llms.txt Template

For AI crawlers and agents:

```markdown
# Project Name

> One-line objective.

## Core Files

- [src/index.ts]: Main entry
- [src/api/]: API routes
- [docs/]: Documentation

## Key Concepts

- Concept 1: Brief explanation
- Concept 2: Brief explanation
```

### MCP-Ready Documentation

For RAG indexing:

- Clear H1-H3 hierarchy
- JSON/YAML examples for data structures
- Mermaid diagrams for flows
- Self-contained sections

---

## 7. Structure Principles

| Principle              | Why                    |
| ---------------------- | ---------------------- |
| **Scannable**          | Headers, lists, tables |
| **Examples first**     | Show, don't just tell  |
| **Progressive detail** | Simple → Complex       |
| **Up to date**         | Outdated = misleading  |

---

> **Remember:** Templates are starting points. Adapt to your project's needs.