Include in resource definition what it is for...

[Panzerbjrn]

I realise this might seem like an odd thing to ask for, but as an example, I'm in the process of trying to figure out how to deploy a custom image, and have had the opportunity to look at many many deployment references, and many of them makes me wonder what they are for.
For Example:
Microsoft.Compute images - Is this for creating images? Grabbing images from somewhere, or deploying VMs from an image? And if the latter, it would be useful for the documentation to say why you'd use this one instead of Microsoft.Compute/virtualMachines?

Microsoft.Network publicIPPrefixes - this is presumably used in creating public IP addresses, but what is it actually for.

I could go on, but I don't want to include too many examples.

[brwilkinson]

The best thing to do is to reference the Docs which now appear to be Learn pages.

E.g. the Product pages --> Compute https://learn.microsoft.com/en-us/azure/?product=compute

Then Virtual Machines --> https://learn.microsoft.com/en-us/azure/virtual-machines/

You can then drill into the specifics... these are the actual Docs. The others are just API/Schema references

https://learn.microsoft.com/en-us/azure/virtual-machines/shared-image-galleries?tabs=azure-powershell

Product page exist for ALL Resource Providers and capabilities.

[Panzerbjrn]

But that still doesn't say what the various resources are for. My example above, Microsoft.Compute images, what is it for? It doesn't say anywhere, and I can't see any reference to it on the learn.microsoft.com site. For documentation to be useful, it needs to give at least some indication of what it is for, and to be findable by searching for the name of the resource you are trying to find documentation for.

It is also not really useful if I am looking at bicep deployment references, and the "documentation" on learn.microsoft.com doesn't contain bicep information.

[brwilkinson]

If you are unfamiliar with a resource provider resource type , the best place to start is deploying it is the Azure portal.

[brwilkinson]

Also the Learn Modules are amazing quality and full of tips, tricks and fundamental to advanced information and scenarios.

https://learn.microsoft.com/en-us/training/browse/?products=azure&resource_type=learning%20path

That is the filter for Azure, Learning Paths.

Learning Paths are collections of Modules to cover a set of core concepts, some of these are also aligned around certifications.