From 3c32c92c0b55c6fbfdcb1af06f151ee54ed180c6 Mon Sep 17 00:00:00 2001
From: mirnawong1 <mirna.wong@fishtownanalytics.com>
Date: Wed, 22 Nov 2023 07:32:41 -0500
Subject: [PATCH 1/2] adjust docs config page

---
 .../docs/reference/resource-configs/docs.md   | 50 +++++++++++++++++--
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/website/docs/reference/resource-configs/docs.md b/website/docs/reference/resource-configs/docs.md
index c5e35dd64f4..b188753010f 100644
--- a/website/docs/reference/resource-configs/docs.md
+++ b/website/docs/reference/resource-configs/docs.md
@@ -20,6 +20,9 @@ default_value: {show: true}
 
 <TabItem value="models">
 
+You can configure `docs` behavior for many resources at once by setting in `dbt_project.yml`. You can also use the `docs` config in `properties.yaml` files, to set or override documentation behaviors for specific resources:
+
+
 <File name='models/schema.yml'>
 
 
@@ -35,6 +38,18 @@ models:
 
 </File>
 
+<File name='dbt_project.yml'>
+
+```yml
+models:
+  [<resource-path>](/reference/resource-configs/resource-path):
+    +docs:
+      show: true | false
+
+```
+
+</File>
+
 </TabItem>
 
 <TabItem value="sources">
@@ -45,6 +60,20 @@ 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
+seeds:
+  [<resource-path>](/reference/resource-configs/resource-path):
+    +docs:
+      show: true | false
+
+```
+
+</File>
+
 <File name='seeds/schema.yml'>
 
 ```yml
@@ -61,6 +90,20 @@ seeds:
 
 <TabItem value="snapshots">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+snapshots:
+  [<resource-path>](/reference/resource-configs/resource-path):
+    +docs:
+      show: true | false
+
+```
+
+</File>
+
 <File name='snapshots/schema.yml'>
 
 ```yml
@@ -77,6 +120,9 @@ snapshots:
 
 <TabItem value="analyses">
 
+You can use the docs property in YAML files, _except_ in `dbt_project.yml`. Refer to [Analysis properties](/reference/analysis-properties) for more info.
+
+
 <File name='analysis/schema.yml'>
 
 ```yml
@@ -93,9 +139,7 @@ analyses:
 
 <TabItem value="macros">
 
-<!----
-To-do: check this
---->
+You can use the docs property in YAML files, _except_ in `dbt_project.yml`. Refer to [Macro properties](/reference/macro-properties) for more info.
 
 <File name='macros/schema.yml'>
 

From be1c0eb7635e06604d838d081da45495e6e41b74 Mon Sep 17 00:00:00 2001
From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com>
Date: Tue, 19 Dec 2023 08:22:39 -0500
Subject: [PATCH 2/2] Update docs.md

fold in Doug's feedback
---
 .../docs/reference/resource-configs/docs.md   | 28 ++++++++-----------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/website/docs/reference/resource-configs/docs.md b/website/docs/reference/resource-configs/docs.md
index b188753010f..d5f7b6499d8 100644
--- a/website/docs/reference/resource-configs/docs.md
+++ b/website/docs/reference/resource-configs/docs.md
@@ -23,31 +23,29 @@ default_value: {show: true}
 You can configure `docs` behavior for many resources at once by setting in `dbt_project.yml`. You can also use the `docs` config in `properties.yaml` files, to set or override documentation behaviors for specific resources:
 
 
-<File name='models/schema.yml'>
-
+<File name='dbt_project.yml'>
 
 ```yml
-version: 2
-
 models:
-  - name: model_name
-    docs:
+  [<resource-path>](/reference/resource-configs/resource-path):
+    +docs:
       show: true | false
-      node_color: "black"
+
 ```
 
 </File>
 
-<File name='dbt_project.yml'>
+<File name='models/schema.yml'>
+
+  ```yml
+version: 2
 
-```yml
 models:
-  [<resource-path>](/reference/resource-configs/resource-path):
-    +docs:
+  - name: model_name
+    docs:
       show: true | false
-
+      node_color: "black"
 ```
-
 </File>
 
 </TabItem>
@@ -153,8 +151,6 @@ macros:
 ```
 </File>
 
-Also refer to [macro properties](/reference/macro-properties).
-
 </TabItem>
 
 </Tabs>
@@ -162,7 +158,7 @@ Also refer to [macro properties](/reference/macro-properties).
 ## Definition
 The docs field can be used to provide documentation-specific configuration to models. It supports the doc attribute `show`, which controls whether or not models are shown in the auto-generated documentation website. It also supports `node_color` for some node types.
 
-**Note:** hidden models will still appear in the dbt DAG visualization but will be identified as "hidden.”
+**Note:** Hidden models will still appear in the dbt DAG visualization but will be identified as "hidden.”
 
 ## Default
 The default value for `show` is `true`.