snowplow
Consider moving playbook docs (and maybe other docs) to reduce duplication of documentation
With the bigquery release the playbook readmes turn out to be nearly identical to Redshift - Snowflake will likely turn out the same.
It might be easier to reason about and maintain if we have a docs folder for playbook configuration instead.
I think the wider question is, what are the READMEs trying to deliver that can't be better homed on the docs site?
Fair point @alexanderdean - we ended up here because we hadn't had docs written yet when the readmes were created. We used the readmes as basis for docs.
If I'm ignoring that sequence of events - I think there's an argument that right now, it makes more sense to have these specific things in READMEs and have docs only worry about the basic settings. Everything beyond the basics has a default which will only need attention when you're digging into the plumbing of the model.
I plan on discussing with product to iron it out regardless.
I'm curious as to your general opinion about this repo - personally I feel there are a lot of readmes and there's a lot of information to consume (which is hard to avoid with a lot of complexity to explain). What's your view?
I am not sure... I think my general sense is that READMEs are good if you need to interface with the code. If you just want to 'use' the code, then you shouldn't have to look inside a source code repository for information. I think if you imagine READMEs as being consumed from inside an IDE the distinction becomes clearer...
That's a nice way to frame it.
I think I need to mull it over but setting a different config to the default does feel like it's in that territory - maybe you're not changing code but you're digging in to the level that you'd probably be looking at the SQL in depth.
Some other things, however, could probably be best shipped to docs site and removed from repo.
I'll mull this over. Thanks for the input.