Started by Mario, December 14, 2017, 10:41:34 PM

Previous topic - Next topic


If somebody ever considered complaining about the documentation I ship for IMWS endpoints...think again  ;)

I have just wasted four hours trying to get some Microsoft Azure endpoints working. I always got mysterious error messages (numerical codes, without any online reference) or the endpoints insisted that one of the parameters was 'wrong'. And I modeled this 100% based on the official Microsoft documentation.

In the end it turned out that they:

a) Swapped GET with POST  (!!)
b) Published incorrect samples
c) Took great care to be fuzzy in the most critical parts of the documentation.

BIG sigh. It took me 30 minutes to setup everything, get my keys and access tokens and resource allocations, write a sample app in IMatch. And then 4 hours to get a single endpoint call working...

On zee other hand: I can now translate an entire IMatch App  into one of 30 languages by clicking a button  :D

Naturally, the translations are not perfect. But this will be a great help for the users who translate IMatch apps (or IMatch, later). And I can offer apps even in languages for which we don't have a translator yet.


I can feel with you!  :o

But good, that you can see even in such situation also the positive things!  :D
Best wishes from Switzerland! :-)


I hope you made a complete and valid Bug Report!!!   ;D  (Ducking and running now!)


Naturally, the translations are not perfect.
Well, maybe they used there documentation as a test case for the translation AI, and Mr. AI got confused between GET and POST  ;D
Win 10 / 64, IMatch 2018, IMA


Quote from: thrinn on December 15, 2017, 08:07:14 AM
Well, maybe they used there documentation as a test case for the translation AI, and Mr. AI got confused between GET and POST  ;D
Maybe. But I have sometimes the impression that the people writing the documentation for the big houses (especially Microsoft and Apple) just write down what they see on the screen.
Basically the list the options visible in the dialog box, but without further insight or know-how...

Microsoft's developer documentation can be very good, or abysmal.
Since I'm new to all the cognitive service APIs I have to do a lot of digging and reading. And I often find multiple documentations for the same "thing", which offer differ in the details and you have to be very careful, looking at the date, API version, language used etc. to find the correct documentation. Not to mention all the tutorials found on the net or the threads at StackOverflow which often have solutions for no longer existing API versions... ::)


Documentation... one of the LAST things any programmer wants to deal with!   8)