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:
      - trigger: numeric_state
        entity_id: sensor.{domain}_temperature
        below: 18
    action:
      - action: 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

1. Go to integration settings
2. Click "Configure"
3. Re-enter credentials

## Known Limitations

- Limitation 1
- Limitation 2

## Support

- [GitHub Issues](https://github.com/{username}/{repo}/issues)
- [Home Assistant Community](https://community.home-assistant.io/)

## License

MIT

HACS info.md Template

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