Writing docs

The documentation on home-assistant.io is often the first thing people read when they set up a device, build an automation, or get stuck. Every page there was written and improved by the community. A clearer sentence, a missing step, or a fixed screenshot helps everyone who reads that page after you.

You do not need to be a developer. If you can explain something clearly, you can help.

Want to improve this contributor site instead? See Improve this contributor site.

Most people who read the documentation use Home Assistant through its interface, not through YAML files. Write for them first: show the way through the UI, and keep the technical details available for those who need them. The style guide explains how.

• Small fixes take minutes and happen entirely in your browser. A typo, an outdated screenshot, a step that no longer matches the UI. Every page has an Edit link.
• Larger changes, like a new page or a restructured section, are easier with a local copy of the site, so you can preview your work before you share it.

The documentation repository carries skills for AI tools, in .claude/skills/: one for the writing style, one for Markdown and Liquid, one for YAML examples, and document-integration-docs for integration pages. Its instructions tell agents to load them before they edit, and not to invent new automation, script, or dashboard examples unless you ask. Every claim on the page is still yours to check against the code. Contribute with AI tools has the workflow.

• Your first docs fix: fix something small, straight from your browser.
• How the documentation works: where pages live, which branch to use, and how changes go live.

• Structure a page: concepts, tasks, references, and when to use which.
• Preview the site locally: run the documentation on your own machine.
• Document an integration: for developers adding a new integration.
• Move, rename, or remove a page: without breaking links.

• Style guide: language, tone, and formatting.
• Images and videos: screenshots, captions, and embedded videos.
• Liquid helpers: My links, glossary tooltips, and text boxes.
• YAML style: how YAML examples should look.
• Automated checks: what the checks on your pull request look for.
• Integration front matter: every key at the top of an integration page.
• Integration page structure: the sections of an integration page, and the blocks to fill them.
• Brand: the personality and voice of Home Assistant, which every page reflects.

• Readers leave feedback on pages through the Provide feedback link. Those become issues on GitHub, and they are a great place to find something to work on.
• Questions about your change? Ask in your pull request. Reviewers are happy to help you get it right.
• Want to chat about the documentation? Join the #documentation channel on the Home Assistant Discord.