Blueprint schema: slight rephrase (#28484)

source/_docs/blueprint/schema.markdown

@@ -1,25 +1,17 @@
 ---
-title: "Blueprint schema"
+title: "About the blueprint schema"
-description: "The schema for a valid blueprint."
+description: "Introduction to the blueprint schema."
 ---
 
+## The blueprint schema
+
 The configuration schema of a blueprint consists of 2 parts:
 
-- The blueprint high-level metadata, like its name and a description and
+1. The blueprint's high-level metadata: name, description, the input required from the user.
-  the input the blueprint needs from the user.
+2. The schema of the thing the blueprint describes.
-- The schema of the thing the blueprint describes.
 
-The first part is referred to as the blueprint schema and contains mainly the
+The first part is referred to as the *blueprint schema*. It contains the
-blueprint's metadata. The second part depends on what the blueprint is for.
+blueprint's metadata.
-
-For example, in the case of creating a blueprint for an automation, the full
-schema for an [automation](/docs/automation/yaml/) applies.
-
-This page is mainly set up to describe the configuration schema of the
-blueprint metadata. Try our [blueprint tutorial](/docs/blueprint/tutorial/)
-in case you are interested in creating your first blueprint.
-
-## The blueprint schema
 
 The only requirement for a blueprint is a name. In its most basic form,
 a blueprint would look like:
@@ -30,9 +22,12 @@ blueprint:
   domain: automation
 ```
 
-And this is already a valid blueprint. But typically, one would need
+Although this is a valid blueprint, it is not very useful.
-more. For example, user inputs or a description to describe the blueprint's
+
-functionality.
+The second part depends on the use case of the blueprint. For example, if you create a blueprint for an automation, the full
+schema for an [automation](/docs/automation/yaml/) applies.
+
+You can add a description of the blueprint's use case and user inputs.
 
 This is the full blueprint schema:
 
@@ -44,15 +39,14 @@ name:
 description:
   description: >
     The description of the blueprint. While optional, this field is highly
-    recommended. For example, to describe what the blueprint does, or tell more
+    recommended. Describe what the blueprint does and describe the inputs the blueprint provide. The description can
-    about the options inputs of the blueprint provide. The description can
     include [Markdown](https://commonmark.org/help/).
   type: string
   required: false
 domain:
   description: >
-    The domain name this blueprint provides a blueprint for. Currently, only
+    The domain in which this blueprint is used. Currently, only
-    `automation` and `script` are supported.
+    [`automation`](/docs/automation/yaml/) and `script` are supported.
   type: string
   required: true
 author:
@@ -67,7 +61,7 @@ homeassistant:
   keys:
     min_version:
       description: >
-        Minimum required version of Home Assistant to use the blueprint (e.g.
+        Minimum required version of Home Assistant to use the blueprint. For example,
         `2022.4.0`. It is important to set this if the blueprint uses any features
         introduced in recent releases to head off issues.
       type: string
@@ -104,12 +98,12 @@ input:
       required: false
 {% endconfiguration %}
 
-## Blueprint inputs
+### Blueprint inputs
 
-As written in the above schema, a blueprint can accept one (or multiple)
+As described above, a blueprint can accept one (or multiple)
-inputs from the blueprint consumer.
+inputs from the blueprint user.
 
-These inputs can be of any type (string, boolean, list, dictionary), can have
+These inputs can be of any type (string, boolean, list, dictionary). They can have
 a default value and also provide a [selector](/docs/blueprint/selectors/) that
 ensures a matching input field in the user interface.
 
@@ -127,11 +121,11 @@ blueprint:
       name: Example input
 ```
 
-In the above example, `my_input` is the identifier of the input, that can be
+In the above example, `my_input` is the identifier of the input. It can be
-referred to later on using the `!input my_input` custom tag.
+referenced by using the `!input my_input` custom tag.
 
-In this example, no `selector` was provided. In this case, if this blueprint
+In this example, no [`selector`](/docs/blueprint/selectors/) was provided. In the user interface, a text input field would be shown to the user.
-was used in the user interface, a text input field would be shown to the user.
+It is then up to the user to find out what to enter there. Blueprints that come with [selectors](/docs/blueprint/selectors/) are easier to use.
 
 A blueprint can have as many inputs as you like.
 
@@ -148,7 +142,7 @@ variables:
   my_input: !input my_input
 ```
 
-## Example blueprints
+### Example blueprints
 
 The [built-in blueprints][blueprint-built-in]
 are great examples to get a bit of a feeling of how blueprints work.
@@ -207,8 +201,12 @@ action:
     target: !input light_target
 ```
 
-Additional examples, provided by the community, can be found on the
+### Related information
-[community forum][blueprint-forums].
+- [About blueprints](/docs/blueprint/)
+- [Blueprint selectors](/docs/blueprint/selectors/)
+- [Using blueprints in automations](/docs/automation/using_blueprints/)
+- [Tutorial: Create an automation blueprint »](/docs/blueprint/tutorial/)
+- [Blueprint community forum][blueprint-forums]
 
 [blueprint-built-in]: https://github.com/home-assistant/core/tree/dev/homeassistant/components/automation/blueprints
 [blueprint-forums]: /get-blueprints

source/_includes/asides/docs_navigation.html

@@ -110,7 +110,7 @@
         <b>{% active_link /docs/blueprint/ Blueprints %}</b>
         <ul>
           <li>{% active_link /docs/blueprint/tutorial/ Tutorial %}</li>
-          <li>{% active_link /docs/blueprint/schema/ Schema %}</li>
+          <li>{% active_link /docs/blueprint/schema/ Blueprint schema %}</li>
           <li>{% active_link /docs/blueprint/selectors/ Selectors %}</li>
         </ul>
       </li>