search

NetAppDocs / astra-control-service

Open-source documentation for NetApp's Astra service
https://docs.netapp.com/us-en/astra-control-service/
3 stars 4 forks source link

gcloud cli examples for service account creation #111

Closed andrewhatfield closed 2 years ago

andrewhatfield commented 3 years ago

Page: Set up Google Cloud

To accelerate user adoption and reduce friction, it would be great to have gcloud api examples

gcloud iam service-accounts create SERVICE_ACCOUNT_ID \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
netapp-mwallis commented 3 years ago

Hi Andrew, thanks for this suggestion. I'll work with product management to include some useful examples. Also, is this issue a duplicate of https://github.com/NetAppDocs/astra-control-service/issues/110?

andrewhatfield commented 3 years ago

111 and #110 are different issues

netapp-mwallis commented 2 years ago

@andrewhatfield, the GCloud setup documentation here does link to Google documentation, which has API examples for service account creation: https://cloud.google.com/iam/docs/creating-managing-service-accounts#iam-service-accounts-create-rest

Would it help to make it more clear that this link has API examples in the link text itself?

andrewhatfield commented 2 years ago

Yes, make it easy for people without forcing them to jump through hoops.

Give them complete copy and paste instructions including CLI and code

netapp-mwallis commented 2 years ago

Hi @andrewhatfield, understood. Unfortunately I was informed that we have a policy against copying content from other vendors, for several reasons:

Sorry about that. We'll have to settle for linking to the content, but I will make it clearer that the destination link includes API examples as well.

andrewhatfield commented 2 years ago

I'm not suggesting we copy documentation, I'm saying that we should provide all of the necessary steps for our user to complete the tasks required.

Sending a customer to another website to trawl through documentation to work it out themselves is not user friendly.

Just as we provide instructions on how to click through a UI (which changes without our knowledge creating a burden on the user, support, and documentation) we should equally provide the CLI instructions in a clear and concise manner.

On Wed, Jan 12, 2022 at 1:18 AM Michael Wallis @.***> wrote:

Hi @andrewhatfield https://github.com/andrewhatfield, understood. Unfortunately I was informed that we have a policy against copying content from other vendors, for several reasons:

  • We have no control over the content, and it could change at any time and be out of date
  • We don't have permission from Google to reuse their documentation, images, or script / code examples

Sorry about that. We'll have to settle for linking to the content, but I will make it clearer that the destination link includes API examples as well.

— Reply to this email directly, view it on GitHub https://github.com/NetAppDocs/astra-control-service/issues/111#issuecomment-1010066079, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAZU7VKKDBSQVFR72JCT2XDUVRC5ZANCNFSM5FBWBUDA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you were mentioned.Message ID: @.***>

netapp-mwallis commented 2 years ago

Hi @andrewhatfield, I sent you an email regarding this issue earlier. After some content analysis, we're going to close this request for the following reasons:

  1. If we include only the gcloud command examples, some folks might not care about gcloud commands, preferring REST or CLI instead, which means the added content would be of no use to them – they would still need to link out to the Google documentation
  2. The link to Google docs provides access to all methods of performing the task in one place, which is better than we can do in our documentation - and it opens in a new browser tab for them which they can close when they are done
  3. Adding the requested content would make our topic longer and more difficult to parse, and could make things worse if the copied commands become out of date / inaccurate
  4. If we include commands for one task, we should be consistent and include commands for all Google-related tasks, which would lengthen the topic considerably (related to the above point)

Thanks for your understanding. Please reach out with any questions.