Comment by ohaideredevs | Hacker News Reader

Comment by ohaideredevs | Hacker News Reader

Parent Full thread

"cute shitty documentation" - reading the GCP docs has been nothing but a pleasure for me. I genuinely hate most documentation (I am looking at you Microsoft), but GCP is up there in quality, almost standing next to MDN.

Could you give me an example of something you had trouble looking up? I am genuinely curious.

As far as experience - the Cloud hasn't lived up to the promise for me. We often use Azure function apps and debugging them is a pain. Sometimes the function doesn't load at all when you change one thing, etc.

AWS was a bit of a better experience, and I think almost everyone knows what "S3" is. That is to say that AWS immediately springs to mind when you need to store BLOBs.

I have also read about people having a lot of problems with GCPs BigQuery - infrequent, but random downtimes with support not being able to figure out the issue.

Edit: As someone else said below - I do agree that all Google's services have a clear use, whereas AWS and Azure tend to have a lot that you just kind of ignore.

GCP's documentation has an aesthetic quality but is lacking practicality.

Take for example a fundamental usecase: working with a blob storage service through a client library.

Googling "gcp cloud storage java example" and "s3 java example" returns these as top results:

https://cloud.google.com/java/getting-started/using-cloud-st...

https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/...

The AWS doc is clear and gives me exactly what I want: Java code snippets for doing common actions with buckets.

The GCP doc is about a sample bookshelf application? And it starts off by creating a bucket through a terminal command followed by a couple of massive code snippets specific to the example app?

Changing the search terms a bit reveals this:

https://cloud.google.com/storage/docs/creating-buckets#stora...

That's a bit better, but seeing options for the various arguments requires me to copy and paste a non-clickable link from the code snippet, which brings me to another attractive but minimally helpful page.

Another example: renaming a bucket. I find the link easily enough..

https://cloud.google.com/storage/docs/moving-buckets#storage...

But only the first code snippet has code samples of any kind. The remaining steps only have instructions for the console and terminal (and the JSON API if you want to curl against that..)

To me, GCP's documentation just doesn't surface information in a way that's conducive to getting work done quickly.

I agree with this 100%. GCP documentation is not useful when attempting to solve specific problems. It’s good for gaining a general idea of how things work. But how specifically does one bind an ssl cert and key to a load balancer? How specifically should one create a service account to read a secret encrypted with kms? GCP documentation is pretty, it reads well. It’s utterly useless for the intended purpose which is helping people use the google cloud platform.

It really comes down to having code I can copy-paste. Google's documentation tends to be minimalist, like a research paper. One small example for everything, just enough to cover every feature.

AWS is closer to "copy paste this big blob and modify it a bit". A lot less work for people trying to implement. I'm not planning to read all the documentation, I just want something that works. Google almost forces you to in many cases

It’s more that copy paste. It’s a philosophy of what the documentation is for.

If I’m looking at a doc I’m here because I want to do a specific task. The documentation should be task centric like the instructions for a university homework assignment. Imagine you want 30 people to practice a novel task in one evening. You taught them theory in class. Now you want them to try it out. Give them step by step instructions they can use to apply general knowledge to this specific case.

When I’m reading about load balancers and certs I don’t need a textbook. I need examples of specific commands. Instructions on using your tool to do my specific task.

That's true. Ideally it would be both - very clear explanations WITH code snippets, which are important to avoid missing "that one little thing" for half an hour when writing code from scratch.

Once you need more and more advanced use-cases, I think we all eventually discover that Documentation is damn hard, and no one does it perfectly.

In Google's case, I see a few major issues constantly with their documentation.

All of their documentation is focused around "use-cases", so to speak. Finding complete API documentation is a pain in the butt for many of their services; instead, they present sections like "Here's how to do X" "Here's how to do Y". More often than not, these pages are structured like help wizards, beginning with a "pull this example repository", which is the laziest possible way to check a "write documentation" checkbox.

Barring pulling those example repositories, they often put code snippets in-line with the documentation. As far as I can tell (at least for Go), these code snippets are auto-generated from comment directives in the source code which enclose blocks to paste into the documentation. What this means is that its ALWAYS missing crucial things, like import paths. So, its basically useless; you need to look at the example code to do anything.

Overall, I'd take AWS's documentation any day, though it does have some very bad areas (specifically once you start treading out of the SDK and into service libraries, like aws-xray-sdk). No one is perfect, but AWS is the gold standard of any cloud service provider documentation I've used IMO.

Reply on news.ycombinator.com