Tutorials: The New Documentation Experience From Twilio

Tutorials: The New Documentation Experience From Twilio

We’re dead excited to share the latest documentation experience from Twilio: our new Tutorials. Providing annotated walkthroughs of example Twilio applications, Tutorials are intended to provide a clear path for your journey to production.

For these guided tours, we tried to reimagine what a technical documentation experience could be. Code-forward and IDE-like, Tutorials aim to present a sample Twilio application in a familiar setting with the context of your favorite web framework.

It’s the friendly walkthrough you’d get from a fellow developer on your first day in a code base, in tasty online form.

What’s Wrong With Code Tutorials?

We feel a lot of online technical documentation still suffers from the vestiges of offline technical manuals. First we get a huge blob of text to parse through, then maybe a hastily scrawled diagram to show the flow of the application and finally below the fold there is hopefully the code we came to see.

This paradigm has its roots in dead trees. Code examples in docs are illustrations in the same way figures are in books. The prose ends up being the technical explanation you have to lean on, with the code often serving as an incomplete exhibit.

With Tutorials, we tried to reverse this relationship between text and code. Code shouldn’t illustrate the narrative – code should be the narrative.

Code Is The Story

Tutorials is our latest swing at telling stories through code. Instead of describing a code sample with text, Tutorials make code the centerpiece of the experience. You’ll explore an example application step-by-step with an annotated walkthrough that explains what each significant chunk of code does.

Written in the web frameworks you told us you use, we’ve endeavoured to make each Tutorial a non-trivial, production-ready example of how to use Twilio. Beyond stateless samples in a bare language, we’ve aimed to work with the frameworks you’re likely to have in production.

You can learn how to do SMS and MMS notifications in Django, Rails, Laravel, Express and ASP.NET MVC. You can implement Click To Call in Java with servlets and Spring MVC. In total, 109 tutorials are waiting for 19 different use cases using Twilio Voice, SMS, Client and IP Messaging.

Each covers the project setup, configuration, and app architecture you need to deploy with confidence.

Real Use Cases You Need

We got a lot of feedback that our Quickstarts were useful for getting started on a Twilio project. Great for getting to your first text message, phone call or video conversation in five minutes. Developers told us it was unclear how to get their solution into production..

We built Tutorials to address that need, tackling intermediate and advanced Twilio use cases with persistence and significant configuration. Appointment Reminders in Django shows how to use Celery to ensure your reminders get sent at the right time. ETA Notifications in Rails updates ActiveRecord models to represent change of order status for deliveries.

The goal of Tutorials is to push past that initial success with Twilio and get the thing you wanted to do in production with a quickness.

Code You Can Take Home

Each Tutorial is itself a full application you can use as a jumping off point. You can browse the significant files in the Tutorial’s file explorer by clicking the folder 

The source code for each Tutorial is bundled with a permissive open source license. Like Twilio’s helper libraries, Tutorials are MIT licensed, inviting you to use it however you see fit.

Take Tutorials For A Spin

21 different developers contributed their powerful effort over a year and a half to bring you Tutorials – we sincerely hope you find them useful in your journey with Twilio. Take one for a spin today and let us know what you think.

Some of our favorites:

• Two Factor Authentication with Authy
• Workflow Automation
• Click-to-Call
• Automated Survey

We’d love to hear what you think – drop us a line.