Hacker News Reader

Comment by ianchildress | Hacker News Reader

I signed up just to reply to this post and say THIS is exactly how our development team (which write in Go) feels. This post could not be more accurate in terms of trying to deal with the outdated documentation.

#1 The documentation is often months and many versions old.

#2 is the fact that app engine instances have to connect to back end compute engine instances using a public IP is unbelievable. The solution for an app engine instance to communicate with your compute engine app is to use their PubSub api system. To get the PubSub api system to work, see #1. The examples are months outdated and you no longer use the appengine.Context to create your OAuth token, but instead now use context.Context which you learn by going through github issue comments.

Google needs to recognize their great deficiency in documentation to be considered in the same tier as AWS.

View on HN

(Google DevRel here)

We recognize that there's out of date stuff in there :\ This is obviously on us, but if you see something wrong, please use that little 'send feedback' link the upper right corner, as demonstrated in this gifly: http://gifly.com/3SA5/

I just set up an alert set up for feedback with a table flip in the description, so those go right to my inbox.

Great to hear they go straight to your inbox. Usually I have the feeling the stuff that is submitted through the 'Feedback' buttons is never read.

Just to clarify, they all go to someone's inbox. Only the table flip ones go to mine.

(Googler here)

In fact, every piece of feedback goes directly to our bug tracking, and a human being looks at every single one. That's not an excuse, and doesn't mean that we can't do better, but we track it all. The biggest problem is the conversion from item in the bug list to actual changes, and we're working on that!

You should remove the feedback link and instead have hard requirements in your release process for all documentation to be perfect before any code is released.

"Oh the documentation is out of date, why didn't you tell us?" illustrates the problem with Google exactly.

It looks like my previous reply vanished into the ether. Leme try again.

I don't intend to shift any blame here. The feedback link isn't a solution. I know you can't un-see docs and reclaim your lost time.

But, there are a lot of words in there for us to fix, and that feedback does help us prioritize :)

It's the development process that Google needs to fix. Google's development process does not require accurate documentation prior to release.

Understood.

The proof of the pudding is in the eating, right? The only way I can respond to that is by delivering good stuff. It will take time for that evidence to accumulate.

For today I just wanted to communicate that we are paying attention :)

I've recently applied for a few documentation/tech writer positions at google. I'll gladly help with improving your documentation and I live about 1 mile from the googleplex.

That's clever with the table flip and all; it gives you a unique way to get just the responses from this. It's great, seriously, that you're using the tools you have to try to make this situation better.

I bet it's frustrating, though, that you can't do more to address the real problems, like lack of (apparent) incentive to keep this stuff up to date. You have to resort to clever sort-of hacks like "put this magic string in your request so someone will read it". A solution which, I might add, sounds a lot like the problems people are talking about when they talk about inscrutability.

The table flip is more about whimsy than effectiveness. :) Given many options, I usually pick the one that's most fun.

Honestly, I plan to read all of the feedback. I worked on the Firebase docs, and I've see how effective a tight feedback loop can be for improving polish.

In case you're reading on iOS and see only a static image (webm doesn't play, even in Chrome): http://i.gifly.com//media_gifly/3/S/A/5/b/3SA5.mp4

FYI, outside of Google Cloud, it's also the things that Google doesn't document that are frustrating.

An example: Chrome on Android goes beyond the spec by adding limitations on when an Audio element will play, requiring an explicit user action. (https://code.google.com/p/chromium/issues/detail?id=178297)

In that example, the limitation (along with other Chrome limitations, such as all the features that behave differently on HTTPS sites) isn't documented anywhere. Developers have to try it on Android, notice that something is amiss, search for what is going wrong, eventually figure out that Google have made an intentional limitation, and then work around it.

I'm not a fan of Google going beyond limitations that are necessary for security when it comes to Chrome. That said, if it's going to happen, it would be nice to at least save folk some time by documenting it properly.

Reply on news.ycombinator.com