"Creating an AKS Cluster" page may need a refresh

[moio]

Summary

I see several issues with the page. In no special order [DOCS TEAM - Added links to PRs addressing checklist items]:

• #1293 Create an AKS cluster page may need a refresh. Part 1: Commands and section headings #1304 - the structure of the page is inconsistent, with some titles being numbered and others not:

• Azure-specific jargon is outdated: "Azure Active Directory" is now known as "Entra ID". This is also seen in other pages
• Azure-specific jargon is outdated: "Service Principals" are now known as "App Registrations". The page uses both terms in different places, and it is never clarified whether the concept is the same or not. This is also seen in other pages
• #1293 Create an AKS cluster page may need a refresh. Part 1: Commands and section headings #1304 - the --skip-assignment commandline flag is now deprecated in az
• #1293 Create an AKS cluster page may need a refresh. Part 1: Commands and section headings #1304 - in "Setting Up the Service Principal with the Azure Command Line Tool" instructions cover a two-command way to achieve the goal followed by a simpler one-command way. As a user following along I felt tricked into going via the more difficult path needlessly
• #1293 Create an AKS cluster page may need a refresh. Part 1: Commands and section headings #1304 - in the commands, some variables referring to the same value are written differently (as $appId first and CLIENT_ID later). It would help to uniform variable names and "style of declaration"
• it is written between the lines, but not clear in the first read, that some concepts are not uniquely named in Microsoft's jargon (eg. app id and client id being the same thing). Ideally Rancher docs should help users making sense of them
• part of the instructions intersect with those in https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster and they are not completely aligned. It would be good to keep those two pages in sync about common content, or move it to a unique location

I hope this helps

[martyav]

I started researching what needs to be done for the outdated terminology and, unfortunately, many of the references to "Azure AD" or "service principal" are to UI labels in Rancher or Azure. So, we would have to verify the appearance of the Rancher and Azure UIs, not just swap one term for another.

[moio]

cc @richard-cox what is the best way to handle this?