Docs should take a "functions first" approach

[jbw976]

What's Missing?

Functions are the future of Crossplane's experience and how platform engineers should be composing resources. As we move towards making Functions GA, and even plan on deprecating classic patch and transform (crossplane/crossplane#4746), we should be making them more of the "default" path when using Crossplane. New users of Crossplane should be using Functions from the very start of their Crossplane journey.

The most obvious place to update with a "functions first" approach would be the quick start guides that are still currently using classic patch and transform, e.g.:

• https://docs.crossplane.io/v1.16/getting-started/provider-aws-part-2/#create-a-custom-api

Below will track a list of broad areas that we should be updating to use and evangelize Functions more aggressively:

Topics to update

Beta Give feedback

1. https://docs.crossplane.io/v1.16/getting-started/provider-aws-part-2/
2. https://docs.crossplane.io/master/getting-started/provider-azure-part-2/
3. https://docs.crossplane.io/master/getting-started/provider-gcp-part-2/
4. https://docs.crossplane.io/master/concepts/compositions/
5. https://docs.crossplane.io/master/concepts/patch-and-transform/

[bobh66]

The existing Composition Functions documentation needs to include more detailed information regarding the importance of the crossplane.io/composition-resource-name annotation and how it affects reconciliation. Specifically:

• The composition-resource-name MUST be unique within the composition/composite instance
• The composition-resource-name MUST be static for a given resource. If the name changes it will cause the existing resource (with the old name) to be deleted and a new resource will be created, even if nothing else in the resource changes.
• The composition-resource-name SHOULD NOT use a loop index counter as part of the name (bucket-0, bucket-1) unless it is guaranteed that the loop will not reshuffle the indices and cause the names to change

I can open this as a separate issue if needed.