Skip to main content

How Twilio Creates Documentation

· 2 min read
Mari Smirnova
Mari Smirnova
Founder Readme LTD

A summary of Twilio's presentation on transforming their documentation. You can watch the full presentation in one of their videos or read it on their blog.

Background​

Once upon a time, Twilio's documentation contained a lot of text that explained the complex concepts of their service and how everything worked. It was well-organized documentation, comprising 1000 pages maintained by 5 engineers. Everything was good, but why not make it better?

Twilio conducted research, and the documentation feedback was positive—developers liked it. However, when developers were asked to show how they used the documentation, it turned out they were scrolling through the documentation to find code examples. They read code examples, took them if they fit, and continued searching if not. After several unsuccessful attempts, they resorted to Google and eventually found the required documentation page. Developers were not using the table of contents and well-structured menus to find information.

Therefore, Twilio began devising code-first documentation solutions to teach developers how to use their service through code.

Tools to Build Code-First Documentation​

For the documentation site, they used:

  • Wagtail CMS based on Django: With the StreamField tool, they could combine structured and unstructured content. Twilio uses this tool to embed code examples into the documentation.
  • GitHub: They store all code examples in a separate repository and test them as real code. They also receive pull requests from external developers who tried the code examples and know how to improve them.

For analytics and research:

Side Notes​

A few more discoveries by Twilio about developers' behavior:

  • The main thing is to help the developer complete the first step. Developers are more likely to finish a guide if they succeed in the first step.
  • The less text before a code example, the better: pages with 4 sentences before a code example performed twice as well as those with 11 lines before the code example.