[FEATURE REQ] SDK Documentation Improvement

[InteXX]

Library name

The entire Azure SDK

Please describe the feature.

Unfortunately, the SDK is very poorly documented.

First, I'll refer to the rich bounty of SDK code samples that I stumbled upon completely by accident, samples that aren't linked to from any documentation that I've been able to find and that apparently are hidden from easy discovery.

For example, let's look at the Azure.ResourceManager.AppService namespace. The SDK documentation for this, unfortunately quite sparse in terms of how to actually use it, is here:

https://learn.microsoft.com/en-us/dotnet/api/azure.resourcemanager.appservice

Its corresponding (hidden) code samples are here:

https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/websites/Azure.ResourceManager.AppService/samples

There's no reason that the documentation for each class can't link to its corresponding samples.

Next, let's go a step further. Review the documentation for this SDK method:

https://learn.microsoft.com/en-us/dotnet/api/azure.resourcemanager.appservice.appcertificatecollection.createorupdate

Note that the corresponding REST API is shown there, i.e.

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/certificates/{name}

Unfortunately, however, the user is left to wander about aimlessly, trying to find the documentation for that particular REST API call. It's here:

https://learn.microsoft.com/en-us/rest/api/appservice/certificates/create-or-update

But when we load up that page, we also find that there's no link back to the SDK version of the call.

In other words, the REST API documentation doesn't link to the SDK documentation and the converse. Each exists in a silo and is therefore next to impossible for a frustrated developer to discover. And then for that poor chap to try to find the rich bounty of (hidden) SDK samples heretofore mentioned? It's enough to drive him silly.

What a waste of our valuable time that's caused by this unfortunate situation.

Further, the samples that actually ARE linked to from the main Azure developer page are woefully sparse in scope. I'll illustrate.

1. First, go here: https://learn.microsoft.com/en-us/dotnet/azure/.
2. Of the eight sections there, click the lower right one, Get Started - Azure SDK for .NET.
3. In the TOC at the left, click the last child node of the Azure SDK for .NET topic node, SDK example.
4. This takes us to Azure Identity, Resource Management, and Storage sample. Click Browse code.
5. Note the markedly feeble sample code here. To the developer unaware of the hidden SDK samples, this is very discouraging, especially considering the sparse nature of the documentation itself.

In summary:

• The REST API documentation for a given call should link to the SDK equivalent.
• The SDK documentation for a given call should link to the REST API equivalent.
• The SDK documentation for each class should link to its corresponding, currently-hidden SDK samples.

Thank you for considering this significant improvement to the Azure developer documentation.

[InteXX]

@ArthurMa1978

Hello Arthur, how are you!

I'd like to discuss Issue #36309, which unfortunately has just recently been abandoned. In your #36309 (comment) you mentioned that the team had committed to working on it, so the closure last Friday came as an unpleasant surprise.

Thank you for your valuable feedback, @InteXX!

I agree with your points. We are collaborating with multiple teams to enhance the document. This is a massive project that may take a while, but it is very important for all developers and we are committed to investing in it.

That was nearly two years ago. Is there still an interest in making this much-needed improvement to the SDK/API documentation stores?

[jsquire]

Thank you for your feedback. Tagging and routing to the team member best able to assist.