Enterprise-Scale icon indicating copy to clipboard operation
Enterprise-Scale copied to clipboard

Published 20 hours ago • verified publisher icon Azure

Minor documentation update to clarify pre-reqs

Open soderholmd opened this issue 1 year ago • 4 comments

This is a suggestion for a minor documentation update to three pages. It is intended to make sure that pre-requisite resource providers are obvious when following the Learn documentation, as they are not currently mentioned. It is therefore possible that a user follows the link directly from Learn to the Portal and initiates an ALZ deployment without being aware that RPs need enabling, as they are documented separately on the Github wiki.

Current state:

  1. https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/#azure-landing-zone-accelerator has a 'click here to deploy landing zones' button that launches the portal ALZ deployment wizard. It does not make any reference to pre-reqs other than the permissions required at / scope
  2. https://github.com/Azure/Enterprise-Scale/wiki/Deploying-ALZ-Pre-requisites discusses the / scoped permissions but makes only a passing reference to resource providers in the context of AMBA and no link to the pre-reqs page
  3. https://github.com/Azure/Enterprise-Scale/wiki/ALZ-Resource-Provider-Recommendations has a full list of required resource providers
  4. Page 3 above also has a line "To successfully deploy an Enterprise-Scale with a predefined [template] (https://aka.ms/caf/ready/accelerator)...", but the 'template' link is directly to the ALZ portal wizard, not to the Bicep or Terraform templates

From these documents it is unclear when reading the first two that the resource provider pre-reqs exist, and so it is easy to miss them.

Suggestion:

  1. Update the pre-reqs document (no. 2) to include a reference to all pre-reqs including a full list of all required resource providers (i.e. consolidate all pre-reqs into a single doc)
  2. Update the Learn doc (no. 1) with an explicit link to the pre-reqs documentation
  3. Update page no 3. above to link 'template' to a Bicep/Terraform/Portal options landing page, not directly to the portal

soderholmd avatar Jul 24 '24 08:07 soderholmd

Thanks @soderholmd, would you be willing to make these updates?

jtracey93 avatar Jul 25 '24 08:07 jtracey93

@jtracey93 happy to as long as it looks good to you!

soderholmd avatar Jul 25 '24 08:07 soderholmd

Yup LGTM

jtracey93 avatar Jul 25 '24 11:07 jtracey93

Two PRs raised:

https://github.com/MicrosoftDocs/cloud-adoption-framework-pr/pull/5751 https://github.com/Azure/Enterprise-Scale/pull/1735

soderholmd avatar Aug 22 '24 09:08 soderholmd