add config descriptions per user feedback

[mirnawong1]

per user feedback during coalesce, the config sections don't explain the differences between resource-type configs vs general configs.

this pr adds a config description to the resource config section and general config section.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docs-getdbt-com	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 17, 2023 6:43pm

[dbeatty10]

Awesome use of snippets 💪

Practical distinction

At a high level, I'm not aware of a meaningful distinction between resource-specific and general configs that affects end users and how they use dbt.

Conceptual distinction

The only difference I'm aware of:

• "Resource-specific configurations" are applicable to only one dbt resource type and "general configurations" are applicable to multiple resource types.

But I don't know a practical difference that affect how users think and act.

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-path>:

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

    # general configs also available in other resource types
    +enabled: true | false
    +tags: <string> | [<string>]
    +pre-hook: <sql-statement> | [<sql-statement>]
    +post-hook: <sql-statement> | [<sql-statement>]
    +database: <string>
    +schema: <string>
    +alias: <string>
    +persist_docs: <dict>
    +full_refresh: <boolean>
    +meta: {<dictionary>}
    +grants: {<dictionary>}

History

Here are the pull requests where these separate headings originally appeared for each different resource types:

• #111
• #158
• #162
• #705

See also

#3964 has some tables showing which general configs apply to which resources. It does not contain any resource-specific configs.

[mirnawong1]

thank you for your detailed technical comments, i appreciate it. 🙏

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.

[dbeatty10]

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.

The distinctions aren't working for me either. I suspect it's because there isn't really any meaningful distinction between resource-specific configs and general configs.

I'm guessing the reason the two different headers exist is just to make it easier to separate the configs that are unique to that particular resource type. e.g., show which configuration options for the snapshot resource type are different than all the rest of the resource types.

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).

What would be some ways to give insight on how to apply each type of config? Do you think the examples section helps with that?

[mirnawong1]

will create a separate issue to restructure the config pages