Skip to content

docs: rewrite all config UI descriptions for clarity and consistency#1446

Open
florianhorner wants to merge 4 commits intobasnijholt:mainfrom
florianhorner:docs/rewrite-config-descriptions
Open

docs: rewrite all config UI descriptions for clarity and consistency#1446
florianhorner wants to merge 4 commits intobasnijholt:mainfrom
florianhorner:docs/rewrite-config-descriptions

Conversation

@florianhorner
Copy link

@florianhorner florianhorner commented Mar 16, 2026

Summary

Rewrites all 39 config option descriptions from jargon-heavy, emoji-laden text into clean, concise plain English. Adopts the standard Home Assistant pattern: short label + detailed tooltip (via data_description).

Before / After Examples

Option Before After
lights lights: List of light entity_ids to be controlled (may be empty). 🌟 Label: lights · Tooltip: "Light entities controlled by this switch. Leave empty to add lights later."
take_over_control take_over_control: Pause adaptation of individual lights and hand over (manual) control... 🔒 Label: take_over_control · Tooltip: "Pauses adaptation when another source changes a light..."
skip_redundant_commands skip_redundant_commands: Skip sending adaptation commands... 📉Disable if physical light states get out of sync... Label: skip_redundant_commands · Tooltip: "Skips commands when the target state matches the light's last known state, reducing network traffic. Disable if light states drift out of sync."

Key improvements

  • All 39 options now use clean label + tooltip pattern
  • Removed decorative emoji (kept only 2 critical ⚠️ warnings)
  • Front-loaded "what it does" before "how it works"
  • Pure strings change — zero behavior modifications

Companion PR

PR #1450 builds on this work by splitting the 40-option wall into a 5-step guided wizard with room presets.

🤖 Generated with Claude Code

@florianhorner
Copy link
Author

florianhorner commented Mar 16, 2026

What this PR does

This PR rewrites all 39 config option descriptions from jargon-heavy, emoji-laden text into clean, concise plain English. It adopts the standard Home Assistant pattern: short label + detailed tooltip (via data_description).

Before / After Examples

Option Before (label) After (label → tooltip)
lights lights: List of light entity_ids to be controlled (may be empty). 🌟 Label: lights · Tooltip: "Light entities controlled by this switch. Leave empty to add lights later."
take_over_control take_over_control: Pause adaptation of individual lights and hand over (manual) control to other sources that issue light.turn_on calls for lights that are on. 🔒 Label: take_over_control · Tooltip: "Pauses adaptation when another source changes a light. The light stays paused until turned off and on again or reset via the set_manual_control service."
detect_non_ha_changes detect_non_ha_changes: Detects and halts adaptations for non-light.turn_on state changes. Needs take_over_control enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state... Label: detect_non_ha_changes · Tooltip: "Detects changes made outside Home Assistant by polling lights each interval, and pauses adaptation until manually reset. Requires take_over_control. ⚠️ Some lights falsely report an 'on' state..."
skip_redundant_commands skip_redundant_commands: Skip sending adaptation commands whose target state already equals the light's known state. Minimizes network traffic... 📉Disable if physical light states get out of sync with HA's recorded state. Label: skip_redundant_commands · Tooltip: "Skips commands when the target state matches the light's last known state, reducing network traffic. Disable if light states drift out of sync."

Key improvements

  • All 39 options now use clean label + tooltip pattern (before: 15 had descriptions crammed into labels, 0 booleans had tooltips)
  • Removed decorative emoji (kept only 2 critical ⚠️ warnings)
  • Front-loaded the "what it does" before the "how it works"
  • Two independent code reviews found zero issues — this is a pure strings change with no behavior modifications

Companion PR

PR #1450 builds on this work by splitting the 40-option wall into a 5-step guided wizard (Essentials → Sleep → Sun & Timing → Behavior → Workarounds) with room presets. Together these two PRs address the #2 most-cited user frustration (config tedium).

Replace all DOCS strings in const.py with clear, user-friendly
descriptions written with a technical writer mindset. Fix the
update-strings.py heuristic so every option gets a clean label
with a tooltip instead of cramming descriptions into labels.

- Rewrite 38+ option descriptions: plain language, no jargon
- Strip decorative emoji (keep only ⚠️ for genuine warnings)
- Fix update-strings.py: remove 40-char heuristic, all options
  now use the tooltip pattern (data_description) consistently
- Update DOCS_MANUAL_CONTROL and DOCS_APPLY for services
- Regenerate strings.json, en.json, and services.yaml

Addresses feedback from basnijholt#1252, basnijholt#1431, basnijholt#1062

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@florianhorner florianhorner force-pushed the docs/rewrite-config-descriptions branch from d418ec4 to e59bb69 Compare March 18, 2026 01:30
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