Dear Twilio: Read This
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:
- Error in documentation on call forwarding
- typo in documentation (smart quotes)
- documentation has no mention of how to send a dial response (I wish I had kept my breaking test case)
- There's no way to get to application settings from https://www.twilio.com/user/account/phone-numbers/XXXXXXX (just emailed to email@example.com)
- call screening, is a little confusing, conceptually
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
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.
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.
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
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 are a lot of terms that get used to mean different things.
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.
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.
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.
By AJ ONeal
Did I make your day?
Buy me a coffee