azure-dev
azure-dev copied to clipboard
[Doc bug] resource tag for a web app is inconsistent in the docs
In the following docs page, the guidance on how to tag app service resources for deployment is inconsistent. https://docs.microsoft.com/en-us/azure/developer/azure-developer-cli/make-azd-compatible?pivots=azd-create#add-bicep-files
This section states to replace the value web
with the name of the actual resources.
This example shows to use the actual value web
, which I believe is correct.
I think the problem is there are two different and valid interpretations of "replacing web
with the name of your service". I think it's possible to interpret that as "the name of the azure resource (like an app service service) that runs your compute" (and I think that's what Chris had done here) vs "the name of a key in the services
object in azure.yaml
" (which is the intended reading).
Later in the linked documentation, we do say this:
Which tries to say the same thing in a different way. It's interesting to note that that section is the first time we really talk about a "service" in the way azd
thinks about services.
Maybe we need to rework the prose to something like this:
- Add the following code, to add a tag named
azd-service-name
with the value ofweb
to your Azure resource.azd
uses this tag to determine what resource to deploy your application to. The value should match the name of your service as defined inazure.yaml
(and then perhaps this is a link to the anchor'd section later in the prose)?
The above is probably still not great (I'm not a technical writer!), but I think being more explicit about what "service" means in this context (and linking to the stuff about services in the the azure.yaml
file) is helpful. It also explains more of "why" this is done.
Updated: https://docs.microsoft.com/en-us/azure/developer/azure-developer-cli/make-azd-compatible?pivots=azd-create.