[ACR] Incorporate API feedback from UX Study

[annelo-msft]

General

1. Term Artifact and getArtifact() method.

• 4 out of 5 participants did not associate getArtifact() with manifest when being asked to "lock a manifest with digest sha256:9f.... in hello-world repository to prevent it from being deleted".
• The last participant spent some time to read the concept doc and did not have this problem.
• We already have a brief intro of key concept and a link to the service concept doc from README. However, in UX study we told participants to not look at the README unless they are stuck. So this may not be an issue if users read docs and understand the concepts and relationship of terms in ACR.
• AWS ECR uses "images and artifacts" in their doc

  Amazon Elastic Container Registry (ECR) is a fully managed container registry that makes it easy to store, manage, share, and deploy your container images and artifacts anywhere.

• GCP Artifact Registry

  Artifact Registry
  The next generation of Container Registry. Store, manage, and secure your build artifacts.

• ACR uses the hierarchy of Registry > Repository > Artifact in concept doc
• Proposal: keep the current name.

2. No example code snippets of locking manifest/updating manifest properties to README

• we already have an sample, Do we want to add it to the README?
• Proposal: add to the README we already have a sample for a more common scenario: updating tag properties. Decision: not add one for updating manifest properties.

3. Ref doc is dull/Ref doc is not good enough. very short and insufficient, didn't explain what the option does.

• This refers to properties canRead/canWrite/canList/canDelete when being used as input to updateManifestProperties() methods. We got them from swagger. E.g.,

        /// <summary> Delete enabled. </summary>
        public bool? CanDelete { get; set; }
        /// <summary> Write enabled. </summary>
        public bool? CanWrite { get; set;  }
        /// <summary> List enabled. </summary>
        public bool? CanList { get; set;  }
        /// <summary> Read enabled. </summary>
        public bool? CanRead { get; set; }

• Proposal: JS has separate types to pass in these in option bags. Update ref docs
• does this feedback apply to other languages?
  Yes, we would address this in the swagger to have it for all languages.

JavaScript specific

• README issue: import is causing problem. other javascript samples are all using require.
  • Logged [Doc][README] trouble shooting section should use require if the examples in README are JavaScript #15746
• Add more information in the ref doc of listing methods to emphasize the return type is an async iterator.
  • Fixed by [ContainerRegistry] beta.4 minor fixes #15722
• Override toString() to provide useful info when customer calling console.log on async iterator or client/client helper type (ContainerRegistry and RegistryArtifact)
  • This is a broader topic across JS SDK libraries. Started a discussion in JS team channel.
• Some participants were not sure on how to pass in the option bag. [ContainerRegistry] doc improvements #16021
  • Add some code snippets to the ref doc.
  • adding comments to code snippets in the README regarding passing in an option bag.
• updateManifestProperties() parameter options should not be optional
  • Fixed by [ContainerRegistry] beta.4 minor fixes #15722
• too much information when console.log on the error
  • We store request and response in our RestError objects because we think they are useful for customers to diagnose issues.

[jeremymeng]

PR to update ref doc is merged: #16973. There are no more actions in this so closing.