Normesta reg updates 2 #2925
Normesta reg updates 2 #2925
Conversation
normesta
requested review from
gapra-msft,
adreed-msft,
dphulkar-msft,
vibhansa-msft,
seanmcc-msft,
souravgupta-msft and
tanyasethi-msft
as code owners
|
@gapra-msft - I pulled from main, resolved conflicts and attempted to PR against the main branch as you suggested. Looks like there is an automated WIKI step failing due to permissions. Can you help resolve? Thanks! |
I think the wiki docs step only has correct permissions if the source branch is in the AzCopy repo. We can ignore the failure for now and run the step manually once this PR is merged. I have also made a PR to make this step only run on releases for the future. |
|
@normesta the reason why the Wiki update fails is that this PR is not merged. We can ignore it for now. Thanks @gapra-msft for the PR on the wiki action to only trigger on published release in the future. |
@gapra-msft can you pls merge? It sounds like there is a way to merge this and ignore the fail. |
|
@dphulkar-msft could you please take a look and approve if it looks good? I can merge after we get 2 approvals |
Norm from the doc team. Now that the AzCopy reference content is being removed from docs in favor of being hosted in GitHub, I just wanted to perform a final editorial pass on the content. After reviewing the ref content, it appears I've done this before so there's not a whole lot of new recommendations.
Because AzCopy reference content will no longer appear as official Microsoft Docs pages, there's a bit more flexibility on phrasing. I'm offering up some suggestions in this PR. If you don't want to accept any given suggestion, please let me know and I'll update the PR to exclude the change. Here's some notes about some of these proposed updates:
ADLS Gen 2 is something we have scrubbed out of all Data Lake Storage conceptual docs as the term is no longer recommended as a means to describe the offering as Data Lake Storage Gen 1 is no longer available. The preferred way to refer to this set of capabilities is Azure Data Lake Storage on first mention and then Data Lake Storage for each mention thereafter.
Recommend replacing most instances of the term authentication with the term authorization. In docs, we use the term authorization to describe the granting of permission by way of a token, key, or identity as the task is authorizing access based on allowed permissions versus the action of verifying that an identity is valid.
The official way in docs of referring to OAuth auth is Microsoft Entra ID authorization. Admittedly OATH tokens are passed as part of this form of authorization, but if the intent is to describe which type of authorization is used (Key, SAS, or by way of a user or managed identity), then the branding term for that method of authorization is Microsoft Entra ID. Also suggest leading with the preferred methods first as a matter of promoting good security practices. For example, listing Entra ID before Shared Key etc.
Also noticed that the vast majority of the examples append a SAS token. Given complete support for Microsoft Entra ID and that Entra ID is the preferred method of authorization, I suggest adding text to the beginning that all examples assume that you've authorized by using Entra ID. Then, append a SAS token only to those examples that require one (For example on the source of a copy operation). This PR does not implement that suggestion.