Hacker News Reader

Comment by ben_jones | Hacker News Reader

Someone please tell the Google Cloud Platform teams this. So many hello world examples which reek of, "I was told to write documentation but I really hate writing documentation". I mean this in good faith, I think writing documentation for a product you don't actually use is a miserable experience and I hope they can find a better balance...

Writing documentation also seems to be a task you kick out to your junior developers that you'd rather not give more critical assignments to, which is backwards as can be.

View on HN

If there's one documentation that I hate with my gut, that is GCP documentation. Like wtf is going on there. Just to give you an example of how horrible it is, just check their Vision documentation: https://cloud.google.com/vision/docs/

They have quick starts, tutorials and how-to-guides. How are even those things conceptually different at all?. And their reference is just a list of their methods like if I knew out of the box how to use your API. Like, what the heck. Just tell me how to talk to your API in simple terms. How hard is it?

"To use the CGP vision API there are two ways to authenticate and connect. 1) REST 2) SDKS" and then just explain to me how to do it simply.

Don't ramble like if this was the fucking Iliad. Go straight to the point and organize your information better.

It's possible that I'm jaded by non-existing documentation, but skimming over the docs in your link, this actually looks like an example of good documentation*

The API reference in particular you pointed to has a top-level description + linkable reference to each individual method / resource along with brief description. AND, for older versions, as well as a description of "objects" used in the API. I guess it would have been nice to also have a sandbox playground, like some of their other APIs do, but this one is fairly good?

Just curious, what's an example of great API in your mind?

*(possibly not in-depth enough, but I wouldn't be able to tell as a newbie).

In this case, google cloud vision, it seems like the docs are fine. It’s the platform that’s confusing because it requires too much ceremony to get started.

GCP documentation is the worst I have come across so far. The GCP documentation seems to have multiple personalities. It is as if the different parts of the documentation were written by different teams in different corners of the company.

I have to often disregard the documentation and get into the gcloud (their Python-based CLI and API) to understand what the heck is going on and their CLI/API code is no good either. Layers and layers of abstraction in their code only to make some REST API calls. The amount of over-engineering and abstraction that is present in their Python code would put even Java SimpleBeanFactoryAwareAspectInstanceFactory developers to shame.

It's not their documentation that is bad, it's the architecture. Too many layers, and things glued together. Where you need to make additional abstractions just to make sense of it all, ending up with a million LOC just to copy something from A to B.

For example integrating support for Google Drive took months, where I ended up using a third party solution, and users are met with a big red warning about my app now being unknown. And the file system is laggy. Compared to integrating Dropbox which took three days and just works. Google Drive probably have thousands of pages of documentation. While Dropbox have one or two.

It's a moat.

Android docs feel the same way, with a side of "eh, just make the interns do it".

Oh god yes, so frustrating

Reply on news.ycombinator.com