In this article
A useful first contribution starts with a problem you can verify—not merely a desire to open a pull request. Removing one real point of confusion can be satisfying precisely because the result is small, concrete, and useful to the next reader.
For Home Assistant, a practical option is a focused correction to an existing user-documentation page. This is an editorial synthesis of the project’s official instructions, not Home Assistant’s designated first-contribution path. If you cannot identify and substantiate a documentation defect, do not manufacture one. Continue reviewing the official developer documentation and linked project repositories for work the project has explicitly requested.
Evidence boundary: This article is based on official documentation retrieved on September 29, 2026. No edit, local preview, automated check, pull request, or maintainer review was performed. It makes no claims about completion time, reviewer response, acceptance, or ease.
1. Confirm that documentation is the right target
Home Assistant publishes distinct development guidance for Core, the frontend, Android, Apple platforms, integrations, translations, and other areas (Home Assistant Developer Docs). The workflow here concerns the home-assistant.io user-documentation website, including its integration documentation. It does not cover application code, companion apps, or software defects.
The documentation site is built with Jekyll, and its pages are written in Markdown; Home Assistant says HTML knowledge is unnecessary for adding a page (Contributing to documentation). A text correction can therefore be proposed without setting up the Home Assistant application, provided you have sound evidence for the change.
First determine whether the page is actually wrong. Unexpected device or integration behavior might indicate a software defect, configuration problem, or unsupported assumption rather than inaccurate documentation. Do not use a prose edit to conceal uncertainty about how the software works.
2. Define one verifiable correction
Record the current wording, the evidence against it, and the smallest correction that resolves the discrepancy. A simple scope statement can keep the proposal disciplined:
Clarify [one prerequisite or instruction] on [one page] because [specific official evidence] contradicts the current wording.
For example:
Hypothetical example—not an observed defect
Page: URL of the affected documentation page
Current wording: “Select the Example Name option.”
Authoritative comparison: Current project documentation calls it “Example Setting.”
Proposed wording: “Select the Example Setting option.”
Validation: Compared both passages and inspected the rendered Markdown; no device or integration test performed.
Use real URLs and quote the relevant material accurately in an actual contribution. A documented contradiction is stronger evidence than a preference such as “this sounds clearer.” Exclude unrelated restructuring, punctuation cleanup, and terminology changes unless they are necessary to fix the identified problem.
3. Choose the appropriate editing workflow
For a small change, Home Assistant documents an Edit or Edit this page link. This browser-based path automatically creates a GitHub fork and lets you propose the change through a pull request. It cannot be used to upload images (Contributing to documentation).
For a larger change, Home Assistant suggests cloning the website repository so you can review the work locally. Integration documentation is stored under source/_integrations/, while other Home Assistant documentation is under source/_docs/. The guide describes a Visual Studio Code devcontainer and a manual environment using Ruby and its dependencies, including commands for generating and serving a local preview (Contributing to documentation).
Use the browser editor for a small text-only correction. Consider a local checkout when a change spans multiple pages, includes images, or otherwise needs broader local review. A development environment does not make a one-line correction more valuable.
4. Target the correct branch
The documentation repository has two principal branches:
- Use
currentfor improvements to existing documentation. - Use
nextwhen documenting a new integration or a feature you are adding to the code.
These branch rules come from Home Assistant’s documentation contribution guide. An ordinary correction to an existing page should therefore target current. Confirm the pull request’s base branch rather than assuming the default is correct.
The supplied guidance does not resolve every mixed case. If a proposal combines an existing-page correction with documentation for an unreleased feature, separate unrelated work where possible or consult the project’s current guidance instead of guessing.
5. Prepare a precise pull request
Before submitting documentation work, Home Assistant directs contributors to read its linked general pull-request review process, select the correct branch, and complete the pull-request template (Contributing to documentation). Read the current linked materials when contributing because they may contain requirements not reproduced here.
In the pull-request description, identify:
- the exact problem;
- the focused correction;
- the evidence supporting it;
- the validation you performed;
- anything you did not test.
Be precise about evidence. Comparing two official passages can support a terminology correction, but it is not a device, configuration, or integration test.
6. Inspect the rendered result
After opening a pull request, you can inspect the proposed site through the Deploy Preview link in the Netlify comment. Contributors working from a local checkout can also run a local preview before submission (Contributing to documentation).
Check headings, lists, links, code blocks, surrounding text, and the original defect. Correct Markdown can still produce an awkward or broken rendered page.
A successful preview is not approval. It shows the proposed page but does not establish that the change is accurate, well scoped, or acceptable to maintainers. Be prepared to revise, split, redirect, or withdraw the proposal after review.
A separate path with executable checks
For a contribution with documented tests, consider Home Assistant’s voice-intent template sentences. This work belongs in the separate Intents repository. Contributions should be limited to one language and one domain because large changes are harder to review. The repository includes language-specific tests; checks can run locally and automatically on pull requests, and failed checks prevent acceptance (Contributing template sentences).
Those scope and testing rules apply specifically to intent-sentence contributions. Do not generalize them to ordinary website documentation.
Pre-submission checklist
- [ ] The change fixes a specific, verifiable documentation problem.
- [ ] The problem belongs in the user-documentation repository.
- [ ] The evidence supports the proposed wording.
- [ ] The patch excludes unrelated rewriting.
- [ ] The workflow fits the size and content of the change.
- [ ] The correct base branch is selected.
- [ ] If using a local checkout, the local preview has been inspected.
- [ ] The current review guidance has been read.
- [ ] The pull-request template is complete.
- [ ] Testing and limitations are described accurately.
- [ ] After opening the pull request, the Netlify Deploy Preview has been checked.
- [ ] Preview results are not presented as maintainer approval.
No comments yet