# Documentation

> Expert technical writing skill. Provides templates for PRD, BRD, SRS, and Engineering docs. Trigger: "Write a PRD", "Document this feature", "Create specs", "Generate readme".

- Skill: `odjaramillo/documentation` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add odjaramillo/documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/odjaramillo/documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: Apache-2.0
- Author: odjaramillo (https://skillmd.com/u/odjaramillo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/odjaramillo/documentation

---


## When to Use

Use this skill when:

- Structuring requirements or specifications
- Documenting business goals or market analysis
- Creating product requirement documents
- Writing technical or architecture documentation

---

## Available Templates (in assets/)

| Category         | Template             | Purpose                             |
| ---------------- | -------------------- | ----------------------------------- |
| **Business**     | `brd.md`             | Business Requirements (Why)         |
| **Business**     | `mrd.md`             | Market Requirements (Who)           |
| **Product**      | `prd.md`             | Product Requirements (What/Vision)  |
| **Specs**        | `srs.md`             | Software Requirements Specification |
| **Specs**        | `frd.md`             | Functional Requirements             |
| **Specs**        | `uird.md`            | UI/UX Requirements                  |
| **Architecture** | `sad.md`             | System Architecture Document        |
| **Architecture** | `trd.md`             | Technical Requirements              |
| **Dev**          | `api-ref.md`         | API Reference Template              |
| **Dev**          | `changelog-entry.md` | Changelog Entry Format              |
| **Dev**          | `project-readme.md`  | README Template                     |

---

## Decision Tree

```
Need business justification?   → Use brd.md
Need market analysis?          → Use mrd.md
Need product vision?           → Use prd.md
Need technical spec?           → Use srs.md
Need user flows?               → Use frd.md
Need UI guidelines?            → Use uird.md
Need system design?            → Use sad.md
Need infra/constraints?        → Use trd.md
Need API docs?                 → Use api-ref.md
Need version notes?            → Use changelog-entry.md
Need project intro?            → Use project-readme.md
```

---

## Workflow

1. **Identify** the document type needed from the table above
2. **Load** the corresponding template from `assets/`
3. **Interview** the user to fill in the `[Placeholders]`
4. **Generate** the filled document

---

## Resources

All templates are in [assets/](assets/).

---

## Detailed Guidelines & Templates

### 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