Home Assistant Integration Documentation

Guide for creating comprehensive documentation for custom integrations.

Documentation Files

| File | Purpose | Location | |------|---------|----------| | README.md | GitHub landing page | Repository root | | info.md | HACS description | Repository root | | docs/*.md | Extended docs | Optional |

README.md Template

# {Integration Name}

[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)
[![GitHub Release](https://img.shields.io/github/release/{username}/{repo}.svg)](https://github.com/{username}/{repo}/releases)

{Brief description of what the integration does.}

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

### HACS (Recommended)

1. Open HACS in Home Assistant
2. Click "Integrations"
3. Click ⋮ → "Custom repositories"
4. Add `https://github.com/{username}/{repo}` as category "Integration"
5. Click "{Integration Name}" → "Download"
6. Restart Home Assistant

### Manual

1. Download the latest release
2. Copy `custom_components/{domain}` to your `custom_components` folder
3. Restart Home Assistant

## Configuration

1. Go to **Settings** → **Devices & Services**
2. Click **+ Add Integration**
3. Search for "{Integration Name}"
4. Follow the setup wizard

### Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| Host | Required | Device IP or hostname |
| Username | Required | Login username |
| Password | Required | Login password |

### Advanced Options

| Option | Default | Description |
|--------|---------|-------------|
| Scan Interval | 30 | Update frequency in seconds |

## Entities

### Sensors

| Entity | Description |
|--------|-------------|
| sensor.{domain}_temperature | Current temperature |
| sensor.{domain}_humidity | Current humidity |

### Switches

| Entity | Description |
|--------|-------------|
| switch.{domain}_power | Main power switch |

## Automation Examples

### Turn on when temperature drops

```yaml
automation:
  - alias: "Low Temperature Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.{domain}_temperature
        below: 18
    action:
      - service: notify.mobile_app
        data:
          message: "Temperature dropped below 18°C"

Troubleshooting

Entity shows "Unavailable"

Check device is powered on
Verify network connectivity
Check integration logs for errors

Authentication Errors

Go to integration settings
Click "Configure"
Re-enter credentials

Known Limitations

Limitation 1
Limitation 2

Support

License

MIT


## HACS info.md Template

```markdown
# {Integration Name}

{Detailed description for HACS store page.}

## What it does

{Explain the integration's purpose and capabilities.}

## Requirements

- Home Assistant 2024.1.0 or later
- {Device/Service name} with firmware X.X or later

## Features

- ✅ Config flow setup
- ✅ Options flow for settings
- ✅ Diagnostics support
- ✅ Automatic reconnection

Documentation Best Practices

Structure

Start with what it does — Users should know in 10 seconds
Installation first — Most common task
Configuration with examples — Show, don't just tell
Entity reference — Complete list of what's created
Troubleshooting — Answer common questions preemptively
Known limitations — Set expectations

Writing Style

Use second person ("you" not "the user")
Be concise — bullet points over paragraphs
Include screenshots where helpful
Keep examples copy-paste ready
Update version numbers in badges

Badges to Include

[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)
[![GitHub Release](https://img.shields.io/github/release/user/repo.svg)](https://github.com/user/repo/releases)
[![GitHub Downloads](https://img.shields.io/github/downloads/user/repo/total.svg)](https://github.com/user/repo/releases)
[![License](https://img.shields.io/github/license/user/repo.svg)](LICENSE)

IQS Documentation Requirements

Bronze

docs-high-level-description: What the integration does
docs-installation-instructions: How to install
docs-removal-instructions: How to remove
docs-actions: Service action documentation

Silver

docs-installation-parameters: All setup fields explained
docs-configuration-parameters: All options explained

Gold

docs-data-update: How/when data updates
docs-examples: Automation examples
docs-known-limitations: What doesn't work
docs-supported-devices: Compatible devices
docs-supported-functions: Feature list
docs-troubleshooting: Common issues
docs-use-cases: Real-world examples

Related Skills

Integration structure → ha-integration-scaffold
HACS publishing → ha-hacs
Quality review → ha-quality-review