refactor docs page

website/docs/docs/build/documentation.md

@@ -2,15 +2,18 @@
 title: "Documentation"
 description: "Learn how good documentation for your dbt models helps stakeholders discover and understand your datasets."
 id: "documentation"
+pagination_next: "docs/build/view-documentation"
 ---
 
+import CopilotBeta from '/snippets/_dbt-copilot-avail.md';
+
 Good documentation for your dbt models will help downstream consumers discover and understand the datasets you curate for them.
 dbt provides a way to generate documentation for your dbt project and render it as a website.
 
-import CopilotBeta from '/snippets/_dbt-copilot-avail.md';
 
 <CopilotBeta resource='documentation' />
 
+
 ## Related documentation
 
 * [Declaring properties](/reference/configs-and-properties)
@@ -24,13 +27,16 @@ import CopilotBeta from '/snippets/_dbt-copilot-avail.md';
 
 ## Overview
 
-dbt provides a way to generate documentation for your dbt project. The documentation for your project includes:
+dbt provides a scalable way to [generate](#generating-documentation) documentation for your dbt project using descriptions and commands. The documentation for your project includes:
 * **Information about your project**: including model code, a DAG of your project, any tests you've added to a column, and more.
 * **Information about your <Term id="data-warehouse" />**: including column data types, and <Term id="table" /> sizes. This information is generated by running queries against the information schema.
+* Importantly, dbt also provides a way to add **descriptions** to models, columns, sources, and more, to further enhance your documentation.
 
-Importantly, dbt also provides a way to add **descriptions** to models, columns, sources, and more, to further enhance your documentation.
+The following sections describe how to [add descriptions](#adding-descriptions-to-your-project) to your project, [generate documentation](#generating-documentation), how to use [docs blocks](#using-docs-blocks), and set a [custom overview](#setting-a-custom-overview) for your documentation.
 
 ## Adding descriptions to your project
+
+Before generating documentation, you'll need to add descriptions to your project resources.
 To add descriptions to your project, use the `description:` key in the same files where you declare [tests](/docs/build/data-tests), like so:
 
 <File name='models/<filename>.yml'>
@@ -56,33 +62,41 @@ models:
           - not_null
 
 ```
-
 </File>
 
-## Generating project documentation
 
-The default documentation experience in dbt Cloud is [dbt Explorer](/docs/collaborate/explore-projects), available on [Team or Enterprise plans](https://www.getdbt.com/pricing/). Use dbt Explorer to view your project's resources (such as models, tests, and metrics), its [metadata](/docs/collaborate/explore-projects#generate-metadata), and their lineage to gain a better understanding of its latest production state.
+### FAQs
+<FAQ path="Project/example-projects" alt_header="Are there any example dbt documentation sites?"/>
+<FAQ path="Docs/document-all-columns" />
+<FAQ path="Docs/long-descriptions" />
+<FAQ path="Docs/sharing-documentation" />
+<FAQ path="Docs/document-other-resources" />
 
-dbt Cloud developer and dbt Core users can use [dbt Docs](/docs/collaborate/build-and-view-your-docs#dbt-docs), which generates basic documentation, but doesn't offer the same speed, metadata, or visibility as dbt Explorer. 
+## Generating documentation
 
 Generate documentation for your project by following these steps:
 
-1. Run `dbt docs generate` — this command tells dbt to compile relevant information about your dbt project and warehouse into `manifest.json` and `catalog.json` files, respectively. 
-2. Ensure you've created the models with `dbt run` to view the documentation for all columns, not just those described in your project.
-3. Run `dbt docs serve` if you're developing locally to use these `.json` files to populate a local website.
+1. Run the `dbt docs generate` [command](/reference/commands/cmd-docs#dbt-docs-generate) to compile relevant information about your dbt project and warehouse into `manifest.json` and `catalog.json` files, respectively. 
+2. Ensure you've created the models with `dbt run` or `dbt build` to view the documentation for all columns, not just those described in your project.
+3. Run the `dbt docs serve` [command](/reference/commands/cmd-docs#dbt-docs-serve) if you're developing locally to use these `.json` files to populate a local website.
 
-To view a resource, its metadata, and what commands are needed in dbt Explorer, refer to [generate metadata](/docs/collaborate/explore-projects#generate-metadata) for more details.
+After adding descriptions and generating documentation, dbt provides two complementary ways to [view documentation](/docs/build/view-documentation):
 
-## FAQs
-<FAQ path="Project/example-projects" alt_header="Are there any example dbt documentation sites?"/>
-<FAQ path="Docs/document-all-columns" />
-<FAQ path="Docs/long-descriptions" />
-<FAQ path="Docs/sharing-documentation" />
-<FAQ path="Docs/document-other-resources" />
+- [**dbt Docs**:](/docs/build/view-documentation#dbt-docs) A static documentation site with model lineage, metadata, and documentation that can be hosted on S3, Netlify, or your own web server. Available on dbt Core or dbt Cloud Developer plans.
+- [**dbt Explorer**](/docs/collaborate/explore-projects): Builds upon dbt Docs to provide a dynamic, real-time interface with enhanced metadata, customizable views, deeper project insights, and collaboration tools. Available on dbt Cloud Team or Enterprise plans.
+
+For more details on how to view documentation, see [View documentation](/docs/build/view-documentation).
 
 ## Using docs blocks
+
+Docs blocks can contain arbitrary markdown, but they must be uniquely named. 
+
 ### Syntax
-To declare a docs block, use the jinja `docs` tag. Docs blocks can contain arbitrary markdown, but they must be uniquely named. Their names may contain uppercase and lowercase letters (A-Z, a-z), digits (0-9), and underscores (_), but can't start with a digit.
+To declare a docs block, use the jinja `docs` tag. Their names may contain:
+- uppercase and lowercase letters (A-Z, a-z)
+- digits (0-9)
+- underscores (_)
+- can't start with a digit.
 
 <File name='events.md'>
 
@@ -102,7 +116,7 @@ The events in this table are recorded by [Snowplow](http://github.com/snowplow/s
 
 </File>
 
-In the above example, a docs block named `table_events` is defined with some descriptive markdown contents. There is nothing significant about the name `table_events` — docs blocks can be named however you like, as long as the name only contains alphanumeric and underscore characters and does not start with a numeric character.
+In this example, a docs block named `table_events` is defined with some descriptive markdown contents. There is nothing significant about the name `table_events` — docs blocks can be named however you like, as long as the name only contains alphanumeric and underscore characters and doesn't start with a numeric character.
 
 ### Placement
 
@@ -118,9 +132,8 @@ Docs blocks should be placed in files with a `.md` file extension. By default, d
 
 </VersionBlock>
 
-
 ### Usage
-To use a docs block, reference it from your `schema.yml` file with the [doc()](/reference/dbt-jinja-functions/doc) function in place of a markdown string. Using the examples above, the `table_events` docs can be included in the `schema.yml` file as shown below:
+To use a docs block, reference it from your `schema.yml` file with the [doc()](/reference/dbt-jinja-functions/doc) function in place of a markdown string. Using the examples above, the `table_events` docs can be included in the `schema.yml` file as shown here:
 
 <File name='schema.yml'>
 
@@ -147,7 +160,11 @@ In the resulting documentation, `'{{ doc("table_events") }}'` will be expanded t
 ## Setting a custom overview
 *Currently available for dbt Docs only.*
 
-The "overview" shown in the dbt Docs website can be overridden by supplying your own docs block called `__overview__`. By default, dbt supplies an overview with helpful information about the docs site itself. Depending on your needs, it may be a good idea to override this docs block with specific information about your company style guide, links to reports, or information about who to contact for help. To override the default overview, create a docs block that looks like this:
+The "overview" shown in the dbt Docs website can be overridden by supplying your own docs block called `__overview__`. 
+
+- By default, dbt supplies an overview with helpful information about the docs site itself.
+- Depending on your needs, it may be a good idea to override this docs block with specific information about your company style guide, links to reports, or information about who to contact for help. 
+- To override the default overview, create a docs block that looks like this:
 
 <File name='models/overview.md'>
 
@@ -168,7 +185,9 @@ as well as the repo for this project \[here](https://github.com/dbt-labs/mrr-pla
 *Currently available for dbt Docs only.*
 
 You can set different overviews for each dbt project/package included in your documentation site
-by creating a docs block named `__[project_name]__`. For example, in order to define
+by creating a docs block named `__[project_name]__`. 
+
+For example, in order to define
 custom overview pages that appear when a viewer navigates inside the `dbt_utils` or `snowplow` package:
 
 <File name='models/overview.md'>
@@ -190,48 +209,3 @@ up to page views and sessions.
 ```
 
 </File>
-
-## Navigating the documentation site
-
-Use [dbt Explorer](/docs/collaborate/explore-projects) for a richer documentation experience and more interactive experience for understanding your project's resources and lineage. Available on [Team or Enterprise plans](https://www.getdbt.com/pricing/).
-
-For additional details on how to explore your lineage and navigate your resources, refer to [dbt Explorer](/docs/collaborate/explore-projects).
-
-<Lightbox src="/img/docs/collaborate/dbt-explorer/example-model-details.png" width="100%" title="Example of resource details" />
-
-<Expandable alt_header="For dbt Docs">
-If you're using the dbt Docs interface, you can navigate to the documentation for a specific model. That might look something like this:
-
-<Lightbox src="/img/docs/building-a-dbt-project/testing-and-documentation/f2221dc-Screen_Shot_2018-08-14_at_6.29.55_PM.png" title="Auto-generated documentation for a dbt model"/>
-
-Here, you can see a representation of the project structure, a markdown description for a model, and a list of all of the columns (with documentation) in the model.
-
-From the dbt Docs page, you can click the green button in the bottom-right corner of the webpage to expand a "mini-map" of your DAG. This pane (shown below) will display the immediate parents and children of the model that you're exploring.
-
-<Lightbox src="/img/docs/building-a-dbt-project/testing-and-documentation/ec77c45-Screen_Shot_2018-08-14_at_6.31.56_PM.png" title="Opening the DAG mini-map"/>
-
-In this example, the `fct_subscription_transactions` model only has one direct parent. By clicking the "Expand" button in the top-right corner of the window, we can pivot the graph horizontally and view the full <Term id="data-lineage">lineage</Term> for our model. This lineage is filterable using the `--select` and `--exclude` flags, which are consistent with the semantics of [model selection syntax](/reference/node-selection/syntax). Further, you can right-click to interact with the DAG, jump to documentation, or share links to your graph visualization with your coworkers.
-
-<Lightbox src="/img/docs/building-a-dbt-project/testing-and-documentation/ac97fba-Screen_Shot_2018-08-14_at_6.35.14_PM.png" title="The full lineage for a dbt model"/>
-
-</Expandable>
-
-## Deploying the documentation site
-
-With dbt Cloud, use [dbt Explorer](/docs/collaborate/explore-projects) automatically retrieves the metadata updates after each job run in the production or staging deployment environment so it always has the latest results for your project &mdash; meaning it's always automatically updated after each job run.
-
-:::caution Security
-
-The `dbt docs serve` command is only intended for local/development hosting of the documentation site. Please use one of the methods listed below (or similar) to ensure that your documentation site is hosted securely!
-
-:::
-
-#### For dbt Docs users
-
-dbt's documentation website was built to make it easy to host on the web. The site is "static,” meaning you don't need any "dynamic" servers to serve the docs. You can host your documentation in several ways:
-
-* Use [dbt Cloud's](/docs/collaborate/build-and-view-your-docs) default documentation experience with [dbt Explorer](/docs/collaborate/explore-projects).
-* Host on [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) (optionally [with IP access restrictions](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html#example-bucket-policies-use-case-3))
-* Publish with [Netlify](https://discourse.getdbt.com/t/publishing-dbt-docs-to-netlify/121)
-* Use your own web server like Apache/Nginx
-

website/docs/docs/build/view-documentation.md

@@ -0,0 +1,85 @@
+---
+title: "View documentation"
+description: "Learn how good documentation for your dbt models helps stakeholders discover and understand your datasets."
+id: "view-documentation"
+---
+
+dbt provides an intuitive and scalable way to write, version-control, and share documentation for your dbt models. You can write [descriptions](/docs/build/documentation#adding-descriptions-to-your-project) (in plain text or markdown) for each resource, and then generate and view documentation to gain shared context for your dbt project.
+
+You can view documentation in two complementary ways, depending on your needs:
+
+| Option | Description | Availability |
+|------|-------------|--------------|
+| [**dbt Docs**](#dbt-docs) | Generates a static website with model lineage, metadata, and documentation that can be hosted on S3, Netlify, or your own web server. | dbt Core or dbt Cloud Developer plans |
+| [**dbt Explorer**](/docs/collaborate/explore-projects) | Recommended and the default documentation experience in dbt Cloud. Builds on dbt Docs to provide a dynamic, real-time interface with richer [metadata](/docs/collaborate/explore-projects#generate-metadata), customizable views, deep insight into your project and resources, and collaborative tools. | dbt Cloud Team or Enterprise plans |
+
+## Navigating your documentation
+The following sections describe how to navigate your documentation in dbt Explorer and dbt Docs.
+
+### dbt Explorer <Lifecycle status="team,enterprise" />
+
+[dbt Explorer](/docs/collaborate/explore-projects) offers a dynamic, interactive way to explore your models, sources, and lineage.
+To access dbt Explorer, navigate to the **Explore** option in the dbt Cloud navigation menu.
+
+<DocCarousel slidesPerView={1}>
+
+<Lightbox src="/img/docs/collaborate/dbt-explorer/example-model-details.png" width="95%" title="Example of resource details" />
+
+<Lightbox src="/img/docs/collaborate/dbt-explorer/explorer-main-page.gif" width="95%" title="Access dbt Explorer from dbt Cloud by clicking Explore in the navigation."/>
+
+</DocCarousel>
+
+dbt Explorer offers users a comprehensive suite of features to enhance data project navigation and understanding, like:
+
+- Interactive lineage visualization to visualize your project's DAG to understand relationships between resources. 
+- Comprehensive resource search bar with filters to help find project resources efficiently and quickly.
+- Model performance insights to access metadata on dbt Cloud runs for in-depth analysis of model performance and quality. 
+- Project recommendations to receive suggestions to improve test coverage and documentation across your data estate. 
+- Data health signals to monitor the health and performance of each resource through data health indicators. 
+- Model query history to track consumption queries on your models to gain deeper insights into data usage. 
+- Auto-exposures to automatically expose relevant data models from tools like Tableau to enhance visibility. 
+
+For additional details and instructions on how to explore your lineage, navigate your resources, view model query history and data health signals, feature availability, and more &mdash; refer to [Discover data with dbt Explorer](/docs/collaborate/explore-projects).
+
+### dbt Docs
+
+If you're using the dbt Docs interface, available on dbt Core or dbt Cloud Developer plans, you can navigate to the documentation for a specific model. That might look something like this:
+
+<Lightbox src="/img/docs/building-a-dbt-project/testing-and-documentation/f2221dc-Screen_Shot_2018-08-14_at_6.29.55_PM.png" title="Auto-generated documentation for a dbt model"/>
+
+Here, you can see a representation of the project structure, a markdown description for a model, and a list of all of the columns (with documentation) in the model.
+
+From the dbt Docs page, you can click the green button in the bottom-right corner of the webpage to expand a "mini-map" of your DAG. This pane (shown below) will display the immediate parents and children of the model that you're exploring.
+
+<Lightbox src="/img/docs/building-a-dbt-project/testing-and-documentation/ec77c45-Screen_Shot_2018-08-14_at_6.31.56_PM.png" title="Opening the DAG mini-map"/>
+
+In this example, the `fct_subscription_transactions` model only has one direct parent. By clicking the "Expand" button in the top-right corner of the window, we can pivot the graph horizontally and view the full <Term id="data-lineage">lineage</Term> for our model. This lineage is filterable using the `--select` and `--exclude` flags, which are consistent with the semantics of [model selection syntax](/reference/node-selection/syntax). Further, you can right-click to interact with the DAG, jump to documentation, or share links to your graph visualization with your coworkers.
+
+<Lightbox src="/img/docs/building-a-dbt-project/testing-and-documentation/ac97fba-Screen_Shot_2018-08-14_at_6.35.14_PM.png" title="The full lineage for a dbt model"/>
+
+## Deploying the documentation site
+
+Effortlessly deploy documentation in dbt Explorer or dbt Docs to view your project documentation and make it available to your team to collaborate.
+
+:::caution Security
+
+The `dbt docs serve` command is only intended for local/development hosting of the documentation site. Please use one of the methods listed in the next section (or similar) to ensure that your documentation site is hosted securely!
+
+:::
+
+### dbt Explorer <Lifecycle status="team,enterprise" />
+
+
+dbt Explorer automatically updates documentation after each production or staging job run using the metadata generated after each job run. This means it always has the latest results for your project &mdash; no manual deployment needed. For details on how dbt Explorer uses metadata to automatically update documentation, refer to [Generate metadata](/docs/collaborate/explore-projects#generate-metadata). 
+
+To learn how to deploy your documentation site, see [Build and view your docs with dbt Cloud](/docs/collaborate/build-and-view-your-docs).
+
+### dbt Docs
+dbt Docs was built to make it easy to host on the web. The site is "static," meaning you don't need any "dynamic" servers to serve the docs. You can host your documentation in several ways:
+
+* Host on [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) (optionally [with IP access restrictions](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html#example-bucket-policies-use-case-3))
+* Publish with [Netlify](https://discourse.getdbt.com/t/publishing-dbt-docs-to-netlify/121)
+* Use your own web server like Apache/Nginx
+* If you're on a dbt Cloud Developer plan, see [Build and view your docs with dbt Cloud](/docs/collaborate/build-and-view-your-docs#dbt-docs) to learn how to deploy your documentation site.
+
+For a more seamless experience, use [dbt Explorer](/docs/collaborate/explore-projects) as the recommended documentation experience in dbt Cloud.