Second pass on triggers and conditions documentation

[abb848]

Roadmap opportunity

This epic is not part of a roadmap item.

Description

Placeholder epic for iteration and polish work on the triggers and conditions documentation. Items raised during review of the initial documentation pass will be added here as tasks.

Deliverables/features

Summarized tasks based on the comments so far:

• Review pages with Good to know sections and identify content that is really a prerequisite.
  • Add a Prerequisites section near the top of trigger, condition, and action pages where needed.
  • Move prerequisite-style content from Good to know into Prerequisites.
  • Keep Good to know only for helpful context that is not required before using the feature.
• Check trigger option tables for Trigger when / behavior.
  • Mark Trigger when / behavior as not required where applicable.
  • Add the default value for Trigger when / behavior where applicable.
• Review pages that use the heading More examples.
  • Rename More examples to Automation examples where the examples are automations.
• Review Related triggers, Related conditions, and Related actions sections.
  • Make related-section headings and intro text consistent across trigger, condition, and action pages.
• Add short descriptions to bullet points in automation examples where the current labels are unclear.
• Review the main Actions page for navigation issues as the list grows.
• Explore grouping or filtering actions by type, such as platform actions, built-in integration actions, and third-party integration actions.
• Identify whether refactoring to use shared includes, like in Refactor threshold trigger and condition docs into shared includes home-assistant.io#45719 can be reused for these documentation improvements.

Completion criteria

Implementation of the above

Additional context

Initial documentation pass: #42

[fdmarcin]

This could include refactoring like in home-assistant/home-assistant.io#45719

[fdmarcin]

Suggestion: Move the "Good to know" section higher on the page, for example, above the options sections.

Related follow-up: trigger, condition, and action pages' "Good to know" sections often contain what are actually prerequisites. Standardize on a "Prerequisites" section that's high on the page and move those there.

[fdmarcin]

Improvement: make sure "Trigger when" / behavior is listed as not required and default value is listed:

Example from vacuum.docked

[Laufmaschine]

Feedback from user here: home-assistant/home-assistant.io#45959. For example, we can consider to:

• change title More examples to Automation examples.
• change title Related triggers or introduction "These triggers / conditions / actions work well alongside this one:".
• add description of bullet points in automation examples.

[Laufmaschine]

Feedback from user here: home-assistant/home-assistant.io#45427

In the Actions page, "it would be great to consider adding categorization or filters to distinguish between:

• Platform actions - e.g. Light, Vacuum, Select
• Built-in integration actions - e.g. Backup
• Third-party integration actions - e.g. ntfy

This would make it much easier to navigate as the page grows."

[fdmarcin]

Summarized tasks based on the comments so far:

• Review pages with Good to know sections and identify content that is really a prerequisite.
  • Add a Prerequisites section near the top of trigger, condition, and action pages where needed.
  • Move prerequisite-style content from Good to know into Prerequisites.
  • Keep Good to know only for helpful context that is not required before using the feature.
• Check trigger option tables for Trigger when / behavior.
  • Mark Trigger when / behavior as not required where applicable.
  • Add the default value for Trigger when / behavior where applicable.
• Review pages that use the heading More examples.
  • Rename More examples to Automation examples where the examples are automations.
• Review Related triggers, Related conditions, and Related actions sections.
  • Make related-section headings and intro text consistent across trigger, condition, and action pages.
• Add short descriptions to bullet points in automation examples where the current labels are unclear.
• Review the main Actions page for navigation issues as the list grows.
• Explore grouping or filtering actions by type, such as platform actions, built-in integration actions, and third-party integration actions.
• Identify whether refactoring to use shared includes, like in Refactor threshold trigger and condition docs into shared includes home-assistant.io#45719 can be reused for these documentation improvements.