Update dbt_project.yml.md (#5545)

this pr adds additiona clarification on the dash and underscores rules
for the `dbt_project.yml` and other configs. [relevant slack
thread](https://dbt-labs.slack.com/archives/C05FWBP9X1U/p1716268955554979?thread_ts=1715189163.754789&cid=C05FWBP9X1U)

website/docs/docs/build/saved-queries.md

@@ -119,6 +119,8 @@ saved-queries:
 ```
 </File>
 
+For more information on `dbt_project.yml` and config naming conventions, see the [dbt_project.yml reference page](/reference/dbt_project.yml#naming-convention).
+
 #### Where clause
 
 Use the following syntax to reference entities, dimensions, time dimensions, or metrics in filters and refer to [Metrics as dimensions](/docs/build/ref-metrics-in-filters) for details on how to use metrics as dimensions with metric filters:

website/docs/docs/build/semantic-models.md

@@ -144,6 +144,8 @@ Semantic models support [`meta`](/reference/resource-configs/meta), [`group`](/r
         some_key: some_value
   ```
 
+For more information on `dbt_project.yml` and config naming conventions, see the [dbt_project.yml reference page](/reference/dbt_project.yml#naming-convention).
+
 </VersionBlock>
 
 ### Name

website/docs/reference/configs-and-properties.md

@@ -5,7 +5,8 @@ title: Configs, properties, what are they?
 Resources in your project—models, snapshots, seeds, tests, and the rest—can have a number of declared **properties**. Resources can also define **configurations**, which are a special kind of property that bring extra abilities. What's the distinction?
 - Properties are declared for resources one-by-one in  `properties.yml` files. Configs can be defined there, nested under a `config` property. They can also be set one-by-one via a `config()` macro (right within `.sql` files), and for many resources at once in `dbt_project.yml`.
 - Because configs can be set in multiple places, they are also applied hierarchically. An individual resource might _inherit_ or _override_ configs set elsewhere.
-- You can select resources based on their config values using the `config:` selection method, but not the values of non-config properties
+- You can select resources based on their config values using the `config:` selection method, but not the values of non-config properties.
+- There are slightly different naming conventions for properties and configs depending on the file type. Refer to [naming convention](/reference/dbt_project.yml#naming-convention) for more details.
 
 A rule of thumb: properties declare things _about_ your project resources; configs go the extra step of telling dbt _how_ to build those resources in your warehouse. This is generally true, but not always, so it's always good to check!
 

website/docs/reference/dbt_project.yml.md

@@ -1,23 +1,25 @@
 
 Every [dbt project](/docs/build/projects) needs a `dbt_project.yml` file — this is how dbt knows a directory is a dbt project. It also contains important information that tells dbt how to operate your project.
 
-dbt uses [YAML](https://yaml.org/) in a few different places. If you're new to YAML, it would be worth learning how arrays, dictionaries, and strings are represented.
+- dbt uses [YAML](https://yaml.org/) in a few different places. If you're new to YAML, it would be worth learning how arrays, dictionaries, and strings are represented.
 
 <VersionBlock lastVersion="1.4">
 
-By default, dbt will look for `dbt_project.yml` in your current working directory and its parents, but you can set a different directory using the `--project-dir` flag.
+- By default, dbt looks for the `dbt_project.yml` in your current working directory and its parents, but you can set a different directory using the `--project-dir` flag.
 
 </VersionBlock>
 
 <VersionBlock firstVersion="1.5">
 
-By default, dbt will look for `dbt_project.yml` in your current working directory and its parents, but you can set a different directory using the `--project-dir` flag or the `DBT_PROJECT_DIR` environment variable.
+- By default, dbt looks for the `dbt_project.yml` in your current working directory and its parents, but you can set a different directory using the `--project-dir` flag or the `DBT_PROJECT_DIR` environment variable.
 
-Starting from dbt v1.5 and higher, you can specify your dbt Cloud project ID in the `dbt_project.yml` file using `project-id` under the `dbt-cloud` config. To find your project ID, check your dbt Cloud project URL, such as `https://cloud.getdbt.com/11/projects/123456`, where the project ID is `123456`.
+- Specify your dbt Cloud project ID in the `dbt_project.yml` file using `project-id` under the `dbt-cloud` config. Find your project ID in your dbt Cloud project URL: For example, in `https://cloud.getdbt.com/11/projects/123456`, the project ID is `123456`.
 
 </VersionBlock>
 
-Something to note, you can't set up a "property" in the `dbt_project.yml` file if it's not a config (an example is [macros](/reference/macro-properties)). This applies to all types of resources. Refer to [Configs and properties](/reference/configs-and-properties) for more detail.
+- Note, you can't set up a "property" in the `dbt_project.yml` file if it's not a config (an example is [macros](/reference/macro-properties)). This applies to all types of resources. Refer to [Configs and properties](/reference/configs-and-properties) for more detail.
+
+## Example
 
 The following example is a list of all available configurations in the `dbt_project.yml` file:
 
@@ -242,3 +244,34 @@ vars:
 </File>
 
 </VersionBlock>
+
+## Naming convention
+
+It's important to follow the correct YAML naming conventions for the configs in your `dbt_project.yml` file to ensure dbt can process them properly. This is especially true for resource types with more than one word.
+
+- Use dashes (`-`) when configuring resource types with multiple words in your `dbt_project.yml` file. Here's an example for [saved queries](/docs/build/saved-queries#configure-saved-query):
+
+    <File name="dbt_project.yml">
+
+    ```yml
+    saved-queries:  # Use dashes for resource types in the dbt_project.yml file.
+      my_saved_query:
+        config:
+          +cache:
+            enabled: true
+    ```
+    </File>
+
+- Use underscore (`_`) when configuring resource types with multiple words for YAML files other than the `dbt_project.yml` file. For example, here's the same saved queries resource in the `semantic_models.yml` file:
+
+    <File name="models/semantic_models.yml">
+
+    ```yml
+    saved_queries:  # Use underscores everywhere outside the dbt_project.yml file.
+      - name: saved_query_name
+        ... # Rest of the saved queries configuration.
+        config:
+          cache:
+            enabled: true
+    ```
+    </File>