1.9+ snapshots docs should probably keep the legacy syntax as well

[joellabes]

Contributions

• I have read the contribution docs, and understand what's expected of me.

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

https://docs.getdbt.com/docs/build/snapshots

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

When viewing docs for v1.9 or Versionless, the "Configure snapshots in versions 1.8 and earlier" section says

The latest versions use an updated snapshot configuration syntax that optimizes performance.

This isn't accurate - the code that it generates + runs against the warehouse is going to be the same, but configuring the snapshot in YAML can be more pleasant because there's less fiddly bits. Edit: I've just seen that the 1.8 docs explain that it's because multiple nodes in a single file is trickier to parse. I guess that is true, but in the grand scheme of things it's not a huge deal.

Separate to that, my preference would be to have both styles of configuration provided for new versions of dbt. New versions of dbt have not removed the classic snapshot syntax and people may still need to see how to configure them. Right now, I think that the classic syntax would just get deleted from the docs site once v1.8 goes EOL, which isn't right.

Additional information

No response

[mirnawong1]

hey @joellabes , this is a great callout and sorry for not being clear about it.

• so during beta, we wanted to version block the legacy configs so users building net new snapshots would see the more performant and preferred way to configure them.
• i met with @dbeatty10 to learn about why the config is helpful.
• there is a docs plan to have a separate legacy snapshot page that contains all the legacy configs (incl the .sql file one) so users can find them and we don't lose these specifications. I plan to then rejig that page and link to the legacy page so it's available for all versions if they choose.
• for the legacy page, i'm currently working on it and plan to have it hopefully live by the end of the year.

For the 1.9 bit, i can modify that sentence so it says the following instead:

The latest versions use an updated snapshot configuration syntax that significantly slow down parsing and compilation.

would love to hear your thoughts on this!

[joellabes]

For the 1.9 bit, i can modify that sentence so it says the following instead:

The latest versions use an updated snapshot configuration syntax that significantly slow down parsing and compilation.

How about

The latest versions use a more ergonomic snapshot configuration syntax that also speeds up parsing and compilation.

?