Skip to content

vNext: Apply review feedback on the user documentation - #518

Merged
RobHofmann merged 1 commit into
5.0-devfrom
docs/pedro-review-feedback
Sep 23, 2026
Merged

RobHofmann merged 1 commit into
5.0-devfrom
docs/pedro-review-feedback

Conversation

@RobHofmann

Copy link
Copy Markdown
Owner

What

Follow-up on the documentation split in #517, based on review feedback on the user docs.

Issue policy removed

The "TimeOut / Cannot connect issues will be closed" text is gone from the README and from docs/troubleshooting.md. The cloud route now hands out the encryption key, which removes the main cause behind that policy. The network causes stay covered by the checks on the troubleshooting page, and "How to report a bug" now points to those checks first.

Corrections

  • Entity IDs. Home Assistant chooses them, not the integration. The default is built from the device name and the translated entity name, depends on language and version, and can be changed by the user. Reworded in entities.md, automation-examples.md and the Device Name option in configuration.md.
  • External sensors. The external temperature and humidity sensors only change what the climate entity shows. The unit keeps regulating on its own sensor. configuration.md said this already; entities.md and the README now say it too.
  • Cloud token. configuration.md now explains that the login token is stored in the entry and reused at every load, that only a failing token triggers reauthentication, and that YAML entries reuse it as well. Checked against __init__.py (MQTT transport built from the stored uid, token and region, MqttConnectError raises ConfigEntryAuthFailed) and config_flow.py (YAML import reuses the token of a matching entry). The troubleshooting entry that claimed a login at every setup is corrected.
  • Warning block. "Devices you do not pick are removed from the entry" is now a > [!WARNING] block in both places.
  • Missing feature. Users are told to open an issue when the device answers a property that has no entity yet.
  • README wording. "Every feature the remote has" became "The features on the remote". The comparison with the Home Assistant 2026.8 core integration is dropped.

Checks

  • No em dashes, all relative links and anchors resolve.
  • Docs only, no code changes.

Drop the policy that closes every time out and cannot connect issue. The
cloud route now hands out the encryption key, which removes the main cause
behind that policy, and the troubleshooting page covers the network causes.

Corrections from review:

- Entity IDs are chosen by Home Assistant, not by the integration. Say so
  in entities.md, automation-examples.md and the Device Name option.
- External temperature and humidity sensors only change what the climate
  entity shows. Say so in entities.md and the README, as configuration.md
  already did.
- Explain in configuration.md that the cloud login token is stored in the
  entry and reused at every load, and that only a failing token triggers
  a new login through reauthentication. YAML entries reuse it too. Fix the
  troubleshooting entry that claimed a login happens at every setup.
- Format the "devices you do not pick are removed" note as a warning block.
- Tell users to open an issue when a device answers a property that has no
  entity yet.
- Tone down "every feature the remote has" and drop the comparison with the
  Home Assistant 2026.8 core integration.
@RobHofmann
RobHofmann merged commit acfde45 into 5.0-dev Sep 23, 2026
4 checks passed
@RobHofmann
RobHofmann deleted the docs/pedro-review-feedback branch September 23, 2026 12:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant