dbt-labs / dbt-labs/docs.getdbt.com

Review the structure of resource-specific and general configs pages

Open
#4,510 0 comments 0 reactions 2 assignees Claimed by @mirnawong1 View on GitHub
content improvement
Dominant language
JavaScript
Stars
215
Forks
1.2k
Avg merge
1d 15h
Merged PRs (30d)
130

Description

### Contributions

- [x] I have read the contribution docs, and understand what's expected of me.

### Link to the page on docs.getdbt.com requiring updates

Following on from the discussion in PR https://github.com/dbt-labs/docs.getdbt.com/pull/4448, this issue sets to address the existing structure and layout of the config pages, specifically resource-specific and general configs content. For example, [model configs](https://docs.getdbt.com/reference/model-configs)

@dbeatty10 suggests the following:

**Radical alternative**

So one radical alternative would be to combine the resource-specific and general configs into a single section and then no additional explanations are even needed.

For seeds, the combined listing for dbt_project.yml might look like this (either give or take the inline comments):

seeds:
:

# resource-specific configs only available to seeds
+quote_columns: true | false
+column_types: {column_name: datatype}
+delimiter:

# general configs also available in other resource types
+enabled: true | false
+tags: | []
+pre-hook: | []
+post-hook: | []
+database:
+schema:
+alias:
+persist_docs:
+full_refresh:
+meta: {}
+grants: {}
History
Here are the pull requests where these separate headings originally appeared for each different resource types:

https://github.com/dbt-labs/docs.getdbt.com/pull/111
https://github.com/dbt-labs/docs.getdbt.com/pull/158
https://github.com/dbt-labs/docs.getdbt.com/pull/162
https://github.com/dbt-labs/docs.getdbt.com/pull/705
See also
https://github.com/dbt-labs/docs.getdbt.com/issues/3964 has some tables showing which general configs apply to which resources. It does not contain any resource-specific configs.

**Mirna's perspective**

I think combing them is a great idea, however i do think doing that is still not explicit enough for users. i like the idea of being more explicit so users have more insight into how they can apply each type of config for their own use case, as oppose to inferring it somehow in the comments of header (currently it's inferred via the header, i think).

I've tried to also make it clearer that the resource-specific config is only available that source using props but it's not working for me so I'm going to investigate more

### What part(s) of the page would you like to see updated?

These are the following pages:
https://docs.getdbt.com/reference/model-configs
https://docs.getdbt.com/reference/seed-configs
https://docs.getdbt.com/reference/snapshot-configs
https://docs.getdbt.com/reference/test-configs
https://docs.getdbt.com/reference/source-configs

### Additional information

_No response_

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.