Updates will be kept to every 2 weeks at a maximum
I will be looking at 3 aspects of the developer onboarding experience:
“Twilio (pronounced TWILL-e-o) is a cloud communications platform as a service (PaaS) company based in San Francisco, California. Twilio allows software developers to programmatically make and receive phone calls and send and receive text messages using its web service APIs.” - Wikipedia
Twilio is one of the companies most famous for having an excellent Developer Experience. Their reputation as a “developer first” company is well established.
My first step is to try and learn what it would be like to use Twilio before I sign up. Let’s visit their main site.
I love this simple design. They get straight to the point and explain what they do in plain English. No marketing terms, no jargon, just a simple proposition: APIs for communication.
Twilio has done an excellent job at hiding the complexities of their product line up under a menu that only those of us who know what we are looking to achieve will be able to find and need.
Rather than talking about SIP, TaskRouter, Network Traversal, or any other industry jargon on their frontpage they keep it to a minimum. Yes it’s there, but for those of us new to the platform the messaging is clear and to the point.
Even this menu is pretty straightforward. Links are split in products and use-cases, allowing one to pick our own adventure. Products are split into their separate categories as well.
I follow the Messaging link and eventually end up on a page describing the SMS API.
This is a perfect Demo Unit, it achieves the most essential goals.
At this point I’m happy to continue so I click the big orange button to get started. It takes me to the sign up form.
Twilio’s sign up form asks some very important questions that I love:
These answers can help them better cater their onboarding experience to me. It’s good to see that every question also has an option to answer it with “I don’t know”.
Rather than verifying my email, Twilio verifies my mobile phone number. They do this to battle spam and it allows a new user to directly start sending with a trial account to that number, and that number only.
Once confirmed I am presented with a rather excellent first use experience. It tries to cover a few things:
I take a tour of the console.
I get a few tooltip explanations of where to find what I need. Interesting, but I always feel like these kind of tooltips are a sign of an overcomplicated, confusing UI. If you need them you need to review your UI, not provide more instructions.
After the quick introduction to the console I Get Started with my first implementation.
Because I answered SMS as my “Product I’d use first” when I signed up, I directly get presented with an SMS tutorial.
The first step is to buy a phone number. There’s little explanation as to why, but I kinda like that. I assume they know and they are showing by example.
Cool, I have a new phone number! I even get to change the number if I want, but I don’t really care so I continue. Interestingly here the explanation as to why I need a number does show up.
On to the next step: sending a message. I’d like to point out that all this time it’s clear to me that this is a 4 step process, and I’m now at step 2.
What’s interesting here is that this is not a step where I get to implement some code, instead I can use their console to send an SMS. I need to expand the code sample to see the code I’d need to produce this step myself.
And here is probably the most disapointing thing of the Twilio onboarding experience. This code sample is extremely basic and could be so much better:
Instead I copy paste this code into my text editor and continue with the click-demo instead.
Next up a bit about receiving SMS and replying to them. This is the first flow chart I’ve seen so far. I tend to hate these when they are presented too early, due to information overload, but this one seems to be well timed.
I try out the demo they provided, I send an SMS to my Twilio phone number and promptly get a reply.
Step 4 turns out to not really be a step at all - I like this, always under sell and over deliver your product’s simplicity. Instead it just sends us to the vast documentation Twilio provides.
I copy-pasted some code earlier and I want to quickly test and see if I can make it work on my machine. What I need though is my Twilio phone number and API credentials. It took me a moment to realise that the # icon represents the numbers section, but once I saw it I figured out where to find my number. I do wish this sidebar would just have text on it though. It would just be way more obvious.
Surprisingly in the whole onboarding process I have not been presented with my API credentials, and the phone numbers screen does not have it either. I click around randomly and eventually spot a Show API credentials link in the top right corner.
I click on that link and boom, my API credentials.
With this in place I run my code, install the Twilio gem, and run the code again, and promptly I receive the SMS message I expected.
My next step is to see what exactly the arguments and return types are for the SMS API. I click on the docs icon on the dashboard and end up on the API reference.
I spot the Send SMS & MMS Messages link under the Twilio REST API header and click on it to continue.
This page has a lot of detail on the arguments this API takes: the recipient, the message, and a various array of optional other arguments. It pairs this with some Ruby code, I’m not sure if this is because of my earlier choices or not.
What it’s missing though is the response I can expect from this API. It’s not obvious and there’s no clear links to the documentation for this either.
Eventually I spot the Output link next to the code.
That’s the actual message object that’s returned. It’s not labeled as such in the API, but I figure it must be after clicking around the REST API reference documentation for a bit and finding the Message resource.
In this resource every attribute of the response is described, though one note would be to point out that the names do not match 100% due to the documentation being written for the XML response, not the JSON response. It’s not too hard to go from snake_case to CamelCase though.
I wondered if I was in the wrong place for the kind of documentation I was looking for, so I quickly went over to the Twilio Ruby gem on Github, to see if those docs provided the right kind of links. Sadly those docs were equally as sparse, not pointing to any reference docs from the samples at all.
Finally I want to highlight the email I eventually received from Twilio.
Interestingly here I finally get presented with links to my API credentials. It also features a few segments to give someone who did not finish the Get Started guide another chance to get started.
I love how this email also provides links to some very useful non-Twilio essentials like Ngrok.
Twilio is an example of a developer product that offers a wide variety of solutions within a certain industry. Twilio’s first-use experience is not perfect but still much more advanced than I’ve seen in many other places.
That’s it for this fourth post on Developer Onboarding. Let me know in the comments below what you think of this post and if I should continue. I’d also love to know what company you think I should review next.
I am a freelance Developer Experience designer. If you want to know more about my work have a look at my portfolio and if you’d like for me to help improve your company’s Developer Experience then most definitely reach out to me via Twitter or email!