Skip to main content

Everybody makes mistakes, even Google doc writers

Yesterday I was exploring the new Android SMS Retriever API, since it seemed to promise to make the user's phone verification a much more straight-forward and also permission-less process. 

Soon I got disappointed since it requires to use a paid third-party service such as Twilio...

But at least I got to see something unusual, not everyday one comes across a code syntax error in an official Google documentation.
Can you spot it? (at the end of the second code snippet).




According to the footnote, the last update of that page was on July 7th, so two months and a week ago.

So have I been the first one to notice this? Or maybe just the first one to raise the voice about it? I have also been nice enough to report it to Google.


I came across the above tweet which announces this API to the world, it includes a link to the docs and as you can see, 118 people re-tweeted it and 190 liked it...
Did any of this people bother to open the link and have a look to the docs? 
And I guess fire up Android Studio to play a little with the API is way too much to ask... I am starting to think that there is a significant proportion of posers among the so-called Android devs...

Anyway, as I said at the beginning, everybody makes mistakes, and actually this is a small one, and it is so obvious that I do not think it would block anyone trying to use the API for the first time.

But I think API docs with few code snippets are not enough to engage devs. 
I do not understand why Google (or any other company trying to seduce a community of devs to use their tools) does not make available the source code (through Github ideally) of an example/PoC simple app which uses and highlights the main features of the new API.
IMHO, this should be done for every non-trivial API.
To see complete and working code helps a lot.
This is actually what I did myself in a previous post.
If you are given the complete example code, you can compile it locally, you can run the unit tests and also some use cases.
All of this is incredibly valuable and saves a lot of time to the users-to-be of the API.



Tools
Probably Google uses their own internal tool to write and publish their documentation (some kind of customized and more advance Google Docs). 
I use Confluence and I am quite happy with it, you can tell is by Altassian, I really like their products, they seem to be made by developers for developers, not like many other corporate tools (SharePoint or ServiceNow, just to name a couple).

In Confluence you can insert a properly-formatted snippets of code, however, it would be nice if you could actually select the programming language of the snippet (e.g., Java or C/C#, etc...), so the editor would perform a basic code syntax check
Actually, the technology behind it is not new, the Web IDEs used in most coding challenge sites such as Codility do that and much more.

But until some doc-writing tool provides that functionality or someone invents the "unit tests for docs", I guess we will keep seeing these type of errors in documentation from time to time.

Comments

Popular posts from this blog

Shared Ledger Simulator

I have been interested in the shared/distributed ledger technology (a.k.a. block chain, a.k.a. the magic behind cryptocurrencies) for more than a year already but recently I had finally put real time and effort into it.

And since I believe that the best way to understand something is to get your hands dirty, that is what I have done, after I got a grasp of the core principles (or that is what I thought back then), I decided to code my own shared ledger simulator.

Initially, I also considered to look into the main existing code bases (e.g., the source code of the main/official Bitcoin client/miner or Ethereum's) since they are open source, but seeing code like thisput me off... That file is 3229 lines big!!! Plus it is written in C++.
Do not get me wrong, I truly believe Satoshi Nakamoto (i.e., whoever hides behind that name) is a genius and also a great software developer, but he/she/they for sure did not have readability as their main priority.

I also noticed that some other people h…

Ejemplo de uso de una Open Banking API para encontrar las transacciones de mayor cuantía

Advertencia y disculpas previas: ésta es una de las primeras veces que escribo sobre programación en mi lengua materna (castellano/español) porque el 99% de lo que sé lo he aprendido (y practicado) en inglés, por lo tanto, me disculpo de antemano si los términos técnicos empleados no son los correctos o si utilizo términos directamente en inglés para los cuales existe una versión en español.

Las entidades financieras cada vez se parecen más a empresas tecnológicas y hay quien asegura que el futuro de la banca está en las Open Banking APIs

Pero... ¿para qué sirve una Open Banking API? 
Las Open Banking APIs permiten crear aplicationes basadas principalmente en los datos que posee la entidad suministradora de la API (normalmente un banco).

¿Y quién puede crear esas aplicationes? Entidades o incluso desarrolladores de software individuales que no tienen por qué tener ninguna relación especial con la entidad financiera. Es decir, cualquiera con unos conocimientos intermedios (iba a decir &quo…

Complete (working) code to verify an Android app user phone number through SMS

Update from Thursday September 14th 2017: 
The very same day I posted this (the day before yesterday), I realized that it looked like Google had just made it effectively obsolete


I thought that at least I could claim that I chose a very demanded functionality to blog about, since Google decided to add a new API to provide this very same service.
Even the names are quite similar, I called it "SMS Verifier" and they call it "SMS Retriever".
But after looking into this new Google Services API, I found out that it requires to use a paid third-party service such as Twilio... very disappointing!
So my original post (which follows below) is still relevant after all, since it allows you to verify the user's phone number for free.

Original post: Tuesday September 12th 2017
It was about time for me to give back to the open source community, so I have just pushed the complete (working) code to verify the user's phone number from within an Android app to Github.

When I goo…