runleonarun
commented
4 weeks ago @alison985 This is great feedback. I think it reflects our bigger issues in the docs, for example, what belongs in reference vs docs? and how do we help Cloud and Core users self serve without overwhelming them with docs not relevant to them? We're working on a strategy for all of this and will let you know when we address this issue in particular.
Would you be open to us reaching out to you for feedback?
Contributions
Link to the page on docs.getdbt.com requiring updates
https://docs.getdbt.com/docs/core/connect-data-platform/redshift-setup https://docs.getdbt.com/reference/resource-configs/redshift-configs https://docs.getdbt.com/reference/database-permissions/redshift-permissions https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-redshift-postgresql-alloydb
What part(s) of the page would you like to see updated?
As a dbt user I would like to know where to go to connect to a database so that a) I don't have to wonder what other pages I'm missing, b) I have a full outline of the content for the connector, and c) I'm not flipping through a bunch of doc tabs to set up a connection.
I would expect https://docs.getdbt.com/reference/resource-configs/redshift-configs to be my one stop shop as the central hub of anything related to Redshift connections.
I think it's fine that there are multiple pages as long as they link together. What's hard for me are things like:
I can't tell the whole list of things to consider in troubleshooting in one place. Having multiple pages that I keep scrolling up and down because I loose my place when I'm flipping tabs. I don't have a mental map(outline) of what content there is to reference.
Additional information
I did not include the quick start guide, blog entries, or release notes links in here. As long as those are linked to from the other docs, that's all I would expect for those.
Also note, I totally know that keeping related pages connected and updated, yet not duplicative in an unmaintainable way, is one of the hardest things about doc maintenance. Hopefully the words I've used to frame it here are helpful.