logo CoolAJ86

Dear Twilio: Read This

Published 2013-7-31

Twilio is exciting.

I don't think that the API is perfect, certainly not intuitively obvious, even to the most casual observer, but it's right in the midsection between easy and annoying, which makes it pretty much perfect for something to chew on and savor - more crunch than a water chestnut (yuck), less than... a rock.

But enough with poor analogies - Let's skip ahead to my ranting, because, well, that's what I was asked to do (except that I'm substituting "platform" for "experience").

Here were some things I found early on:

Frustration #1: The Quick Start is a Lie

The first frustrating thing was that I kept seeing the words "Quick Start" and so I kept clicking them - even though they're a lie.

Instead of being short snippets of api code or curl and raw json / xml, they're more involved tutorials that require downloading code and clicking through lots of pages without being able to tell the end from the beginning.

What I'm saying is that assert.isTrue(QuickStart, TL;DR) threw an exception.

Frustration #2: Reading the text is Difficult!

Shades of red and grey are poor choices for readability. Marketing psychologist love the red/black combos (why do you think Google switched to black and red? same as Oracle, Novell, Adobe, Texas Instruments, Lenovo - even Big Blue is flirting with the idea - etc), but it's no good for documentation.

Biege background with grey text and red links?... no bueno.

A lot of the trouble I had finding what I was looking for I'm going to chalk up to difficulty scanning.

I'm used to Github's and NodeJS' documentation. Twilio's docs don't quite stack up in the reader-friendly department.

Frustration #3: Non-MVC Examples

I'll admit, I'm more than a little bit PHP-phobic. I do have a perhaps irrational tendency to believe that because most PHP in incoherent and difficult to understand that any PHP I'm looking at is also incoherent and impossible to understand... which causes me to have difficulty understanding it.

My this-will-probably-be-complicated-o-meter was already on red alert when I saw XML and then with the PHP poked in... doh, I'm a goner! (but I turned out to be wrong about the XML, it's surprisingly well-structured and holds to its own conventions across the API)

In programming we call it recursion. In electrical engineering, a ground loop. In layman's terms, it's just an old-fashioned self-fulfilling prophecy / anxiety attack.

But wait, wait, wait: I legitimately get confused when there's code inline with html / xml / javascript / etc.

The inconsistencies / lack of separation of concerns were difficult for me:

  • Mixed xml with inline code
  • Mixed library code with non-library code
  • Plain xml without accompanying code
  • Route overloading (common with PHP, rare in everything else)
    • /voice should discretely handle a call
    • /voicemail should discretely handle voicemail
    • many of the examples ambiguously handle many things in a single route

Example: nasty inlined code vs using the API.

Documentation grows. It's difficult to update the old bits. It happens.

Frustration #4: Error Console isn't big enough

Once I found it I felt stupid, but it took some googling before I finally realised that I had a Debug Console right at https://www.twilio.com/user/account.

(perhaps I didn't notice it because it wasn't there or was empty until I had a few errors)

I'd suggest having a flash message explaining the debug console the first time someone logs in after having had their first error - and maybe filling in the empty grid space in the docs with "Debugging" (or on the right) - somewhere very visible - and linking to a page that explains the debugging process.

Frustration #5: Duplicate APIs => Bad SEO

There's the RESTful API, the STATEful API, and three clients - JavaScript (browser), iOS, Android, and... oh yeah, the other JavaScript (node) API!

There are a lot of terms that get used to mean different things.

A Conference is, but isn't a Conference.

A Client isn't at all a Client.

This confusion is just the nature of the beast, but perhaps a visual cue - like a big huge NodeJS logo or Chrome/FF/MSIE logos or a server icon at the top of the page to disambiguate - or even different color backgrounds - TwiML is Deep Red, REST is brown... I dunno.

But sometimes I'd end up on the wrong docs and confused as to why what seemed to be the same page of documentation was actually different.

Frustration #6: I have no idea what I'm controlling

This is a big one. I really wish there had been an introductory video to explain the different parts of the system. In fact, I still wish that.

Conceptually this is new... or at least it's not the MVC / REST style I'm used to - it just doesn't fit.

Restructuring my brain around this pattern that honestly doesn't fit well into those paradigms would benefit from some diagrams.

I have a my phone in my hand. I have my friend's phone on the table. I have a Macbook with a browser. I have my server. There's the TwiML API and also the REST API.

And all of these things are doing stuff at the same time!

That's more than I'm usually dealing with.

I'm still not sure I entirely grasp what the TwiML API represents. The control isn't client-server or server-server, but rather the control shifts back and forth.

Follow the control in this scenario:

  • A customer calls my Twilio number on Google Adwords
  • The TwimML contacts my vps with the info
  • My vps responds to the call (which feels like "to my phone") with an on hold message
  • AND in the same message is telling the TwiML server to call my friend's phone
  • My friend answers and enters his pin
  • The TwiML server responds to my vps
    • If I do nothing the calls are now connected
    • BUT if I do something... now I'm lost... I think I'm still controlling my friend's phone?
  • My friend hangs up
  • If I had a Dial action my vps gets another request
    • Has the call ended for both parties at this moment?
    • OR could I issue Dial again immediately and be connected to someone else without "hanging up"?
  • Yet if I join a conference, there's no callback to give me the ConferenceSid... what?

The control flip-flops between the various devices and is sometimes ambigous as to which phone I'm issuing the directive to or what conceptual resource I'm interacting with.

What is a "Call"? It sometimes feels like any of a phone or the server or a session.

Between Dial action, Redirect, StatusCallback, and Fallback - which is right for which?

Back to readabiliy for a sec: The diagrams would be a lot better if they used more directions instead of just right and left (since there are more than 2 devices at play).

Maybe more of a numbered star diagram?

Frustration #9 3/4: NodeJS Docs are Les Miserables

There are just 3 mentions of "node.js" on http://twilio.github.io/twilio-node/! There is exactly one link with "nodejs" in the name, but that doesn't count towards the keywords on the twilio docs page.

That makes it difficult to find, actually. You have to search exactly "twilio node" - not "node twilio" or "twilio nodejs" or "twilio node api" (or at least for the results that Google gives to me).

Ther are several unoffcial twilio modules up on npm and they're dominating the SEO.

I understand the problem of duplication, but having such a sparsely documented module is terribad no bueno (worse than regular no bueno).

Maybe using a JSON-based core documentation that can be used to template out the documentation for each language would be in order?

Anyway, I far too often I get caught up in the intricacies of trying to discover a good library, only to find out that it's easier to do it the hard way.

I found the node api useful for the Client, but not for the TwiML responses.

Recap

Although I found a few inconsistencies in the TwiML API and a few holes in the NodeJS module, the bigger problems are general readability of code, docs, and conceptual understanding.

Awesome #1: The Debugger

I spent somewhere between 30 minutes and a few hours getting occasional "An Application Error has Occured" messages and getting out of them using the trial and error approach of binary search code bingo before I finally realized that the debugger was right in front of my face.

The error messages are extremely helpful (that's rare for error messages). I'm able to pretty much immediately solve any problem I encounter.

Awesome #2: Makes the impossible possible

This should be #1 (I mean, without it there would be no need for a debugger), but I love the debugger too much.

Anyway, I don't know how I could do any voice and sms without Twilio.

Before I knew about Twilio it just seemed too complicated to even approach and now, suddenly, my mind is exploding with all the cool ways I can integrate voice and SMS into whatever I'm working on.

So yeah, it takes a little bit of learning and not everything is intuitive, but it's very doable.

Awesome #3: Evangelists & Support

Those Twilio-ists - or what do you call them? - on StackOverflow are amazing!

I was incredibly impressed by the response to my github issues as well.

Awesome #4: The Price is Right

For my business use cases, the price is reasonable.

I think it would be fun to experiment with using it for day-to-day personal use as well and see what it tallies to.

Awesome #5: It's Exciting

It's genuinely exciting. Exciting enough that I'm still up writing this when I should have long gone to bed.

Goodnight.


By AJ ONeal

If you loved this and want more like it, sign up!


Did I make your day?
Buy me a coffeeBuy me a coffee  

(you can learn about the bigger picture I'm working towards on my patreon page )