[DOCS]: Update docs to recommend the use of team ID over team slug

[stevehipwell]

Describe the need

If the team ID is used there is no need to call the API to lookup the ID from the slug as it's already in state. It also removes the danger that a team might be created with a numeric name which would be confused for an ID.

It might also be worth discussing removing support for using the slug in the next major version to remove this confusion.

SDK Version

No response

API Version

No response

Relevant log output

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[kfcampbell]

Are you referring to the github_repository_collaborators resource edited in #2420 specifically here, or a blanket change for the provider?

[stevehipwell]

A blanket recommendation based on how getTeamID() works.

[stevehipwell]

It might also be worth discussing removing support for using the slug in the next major version to remove this confusion.

@kfcampbell this could be augmented by adding support for a mutually exclusive (to team_id) input team_slug to relevant resources. If added as part of a minor version use of slug via team_id could warn until the next major release when support could be removed.

[stevehipwell]

@kfcampbell after looking at the REST API docs I can see that the team ID endpoints are deprecated. I'll take a look at what it'd take to implement team_slug as a provider wide alternative with both paths being optimised so as to not add additional API calls.

Based on the current code we should still document that when setting team_id the actual ID should be prefered over the slug.