Why use explicit `colocate_with` in create_distributed_table?

[begriffs]

Communication goals (e.g. detailed howto vs orientation)

We received a question in Slack where someone wants to know, "why use colocate_with in a situation where the default colocation group would work?"

Good locations for content in docs structure

This section led to the question: https://docs.citusdata.com/en/v7.3/sharding/data_modeling.html#distributing-tables-by-tenant

How does this work? (devs)

The benefits of colocate_with as I understand it:

• Makes the intention explicit, so Citus will error if the shard count setting has changed since distributing the original table.
• Ability to put tables in different colocation groups when their dist columns happen to be the same type but represent different concepts that are unlikely to be joined.
  • I'm unsure whether this matches a common use case. Could reduce the overhead of the shard rebalancer thinking it needs to keep tables together when in fact it doesn't.

[jonels-msft]

There's now a note about this in http://docs.citusdata.com/en/v8.3/develop/api_udf.html#create-distributed-table but leaving this issue open in case we want to highlight the point in another place.