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

Using Apache Kafka to implement event-driven microservices

When talking about microservices architecture, most people think of a network of stateless services which communicate through HTTP (one may call it RESTful or not, depending on how much of a nitpicker one is).

But there is another way, which may be more suitable depending on the use case at hand.
I am talking about event-driven microservices, where in addition to the classic request-response pattern, services publish messages which represent events (facts) and subscribe to topics (or queues depending on the terminology used) to receive events/messages.

To fully understand and embrace this new software design paradigm is not straight-forward but it is totally worth it (at least looking into it).
There are several interconnected concepts which need to be explored in order to discover the advantages of event-driven design and the evolutionary path which led to it, for example:
Log (including log-structured storage engine and write-ahead log)Materialized ViewEvent SourcingCommand Query Respons…

Vert.x microservices: an (opinionated) application

First of all, sorry for the tautology in the title, a library can be either opinionated or un-opinionated (such as Vert.x is), but an application can only be opinionated.
However, I decided to include "opinionated" to help getting my point across even though is redundant.
The Motivation  I am a big fan of Vert.x and the official documentation is quite good, yet it is not straight-forward to understand how it works and how to use it.
There are a lot of blogs and articles describing Vert.x terminology and its concurrency model.
There are also tons of "Hello World" Vert.x applications on Github, and the rest seem to be just variations of the already typical "Web chat application using Vert.x".
On top of that, many of them are outdated (using AngularJS instead of Angular2+, for example).

The only two exceptions which I found are:
vertx-microservices-workshop: a demo application by the Vert.x development team.
ngrx-realtime-app: proof of concept application focu…

Kafka + WebSockets + Angular: event-driven microservices all the way to the frontend

In the the initial post of the Event-driven microservices with Kafka series (see here or here), I talked about the advantages of using event-driven communication and Kafka to implement stateful microservices instead of the standard stateless RESTful ones.
I also presented the architecture and the source code of a related proof of concept application.

In this post, I would like to show how to extend the asynchronous event-driven communication all the way from Kafka to the Web frontend passing through the Java backend.
Hence, in the first post of this series, we got rid of HTTP as the communication protocol among microservices in the backend, and now we are also replacing it (with WebSockets) as the communication protocol between the frontend and the backend.
Ok, but why would you do that? Because it provides a better experience to the end user!.
Using WebSockets you can build legit real-time user interfaces, the updates are pushed immediately from the server to the client, no need for …