diff --git a/website/docs/reference/dbt_project.yml.md b/website/docs/reference/dbt_project.yml.md
index 59541a81256..6009033d557 100644
--- a/website/docs/reference/dbt_project.yml.md
+++ b/website/docs/reference/dbt_project.yml.md
@@ -18,12 +18,13 @@ By default, dbt will look for `dbt_project.yml` in your current working director
 
 </VersionBlock>
 
-The following is a list of all available configurations in the `dbt_project.yml` file.
-
 :::info YAML syntax
+
 dbt uses YAML in a few different places. If you're new to YAML, it would be worth taking the time to learn how arrays, dictionaries and strings are represented.
 :::
 
+The following is a list of all available configurations in the `dbt_project.yml` file. Something to note, [Macro properties](/reference/macro-properties) aren't supported in the `dbt_project.yml` file:
+
 <File name='dbt_project.yml'>
 
 ```yml
diff --git a/website/docs/reference/macro-properties.md b/website/docs/reference/macro-properties.md
index 91ba52de9ca..3b755cd0107 100644
--- a/website/docs/reference/macro-properties.md
+++ b/website/docs/reference/macro-properties.md
@@ -2,9 +2,9 @@
 title: Macro properties
 ---
 
-Macro properties can be declared in `.yml` files.
+Macro properties can be declared in `.yml` files, except in the `dbt_project.yml` files.
 
-You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders.
+You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in sub-folders.
 
 <File name='macros/<filename>.yml'>
 
diff --git a/website/docs/reference/resource-configs/docs.md b/website/docs/reference/resource-configs/docs.md
index d94b975683d..dff58be8931 100644
--- a/website/docs/reference/resource-configs/docs.md
+++ b/website/docs/reference/resource-configs/docs.md
@@ -17,10 +17,28 @@ default_value: {show: true}
     { label: 'Macros', value: 'macros', },
   ]
 }>
+
 <TabItem value="models">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+name: "your_dbt_project_name"
+version: "1.0.0"
+config-version: 2
+
+models:
+  - name: model_name
+    docs:
+      show: true | false
+```
+</File>
+
 <File name='models/schema.yml'>
 
+
 ```yml
 version: 2
 
@@ -28,7 +46,6 @@ models:
   - name: model_name
     docs:
       show: true | false
-
 ```
 
 </File>
@@ -43,6 +60,22 @@ This property is not implemented for sources.
 
 <TabItem value="seeds">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+name: "your_dbt_project_name"
+version: "1.0.0"
+config-version: 2
+
+seeds:
+  - name: seed_name
+    docs:
+      show: true | false
+```
+</File>
+
 <File name='seeds/schema.yml'>
 
 ```yml
@@ -52,15 +85,29 @@ seeds:
   - name: seed_name
     docs:
       show: true | false
-
 ```
-
 </File>
 
 </TabItem>
 
 <TabItem value="snapshots">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+name: "your_dbt_project_name"
+version: "1.0.0"
+config-version: 2
+
+snapshots:
+  - name: snapshot_name
+    docs:
+      show: true | false
+```
+</File>
+
 <File name='snapshots/schema.yml'>
 
 ```yml
@@ -70,15 +117,29 @@ snapshots:
   - name: snapshot_name
     docs:
       show: true | false
-
 ```
-
 </File>
 
 </TabItem>
 
 <TabItem value="analyses">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+name: "your_dbt_project_name"
+version: "1.0.0"
+config-version: 2
+
+analyses:
+  - name: analysis_name
+    docs:
+      show: true | false
+```
+</File>
+
 <File name='analysis/schema.yml'>
 
 ```yml
@@ -89,16 +150,13 @@ analyses:
     docs:
       show: true | false
 ```
-
 </File>
 
 </TabItem>
 
 <TabItem value="macros">
 
-<!----
-To-do: check this
---->
+You can use the docs property in YAML files, _except_ in `dbt_project.yml`. [Macro properties](/reference/macro-properties) _are not_ supported in the `dbt_project.yml` file. 
 
 <File name='macros/schema.yml'>
 
@@ -109,9 +167,7 @@ macros:
   - name: macro_name
     docs:
       show: true | false
-
 ```
-
 </File>
 
 </TabItem>