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.
"Oh the documentation is out of date, why didn't you tell us?" illustrates the problem with Google exactly.
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 :)
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 :)
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.
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!
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.
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.