As of 2016-02-26, there will be no more posts for this blog. s/blog/pba/
Showing posts with label documentation. Show all posts

I was looking for an API for data in Public Data Explorer, thinking about presenting the data in different visualizations (BigQuery, probably is the right one, Google stuff is too many and too confusing), then I saw this:


Who would list cURL as programming language? Google really needs someone to proofread. I am sure this mistake was made by a writer who added the entry for that Bash example code which utilizes cURL to retrieve data.

As a developer, you wouldn't make such error, this isn't even a simple typo. It must be written by whom didn't have basic knowledge of development environment. They can either let a developer write the draft, then a writer proofreads, or the other way around. Anyway, I doubt this page is proofread.

Last time, only a few days ago, I mentioned issue in Google Docs Spreadsheet's and Analytics documentations. The underlying problem is the same. There seems no developers involved in writing documentation (outside of code), that sounds ridiculous, but that's what I felt after I read their documentation.

And there is a more important issue about the code and other on Google Developer, see the following screenshot:


There is no notes about the license of the code, except the copyright statement in the comment block. If I read this kind of code block anywhere, I would not even try to read it.

The question to be asked is: may you use this example code freely? May you even select the whole code and press Ctrl+C to reproduce?

I don't understand why Google neglects or forgets such important thing: noting copyright and license in every page. (They have legal department, don't they?) To see the permission and license, the fastest way is to click on Terms of Service Site Policies. That's two clicks and only if you know where to read, and I really need to quote:

You will find the following notice at the bottom of many pages on the Google Developers website:
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.

[snip]

You may also find the following notice on the bottom of some pages:
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License.

Okay, which one? Wait a minute, I see neither. WTF.

Garsh, I feel I am too geeky or nerdy. How could I laugh out loud like that?

I was looking for else in for loop. I can never be remembering when will else clause gets executed, so I gotta check up every time. And this is the quote I just read (bold for emphasis):

The for statement in Python differs a bit from what you may be used to in C or Pascal. blah blah blah in the order that they appear in the sequence. For example (no pun intended):

When I saw that bold text, I asked myself how on Earth an official programming language's documentation has that?

And the important thing is I didn't get it first time, but I laughed like an idiot then.