Twilio is regarded as one of the API industry’s leaders, so when, after five years, Twilio changes the documentation format on their developer portal, everybody wants to know why.
Jarod Reyes and Andrew Baker (both developers of Twilio’s developer education team) gave a presentation about the reason for the changes at SIGNAL 2016. Because we found them valuable and wanted to share them with our developer portal mailinglist, we’ll summarize their findings in this blog post.
1. Know what developers don’t need: Narrative vs Code
Twilio considers API documentation to be a product in its own right, not just a supplement of “The Product”. Because developers need documentation to integrate with an API, it plays a key role in the developer experience and overall quality of service. It is crucial to keep documentation valid and to serve it with constantly improved developer experience based on user feedback. Documentation should in the first place be valuable, up-to-date, and easily accessible.
It appears from Twilio’s user tests that developers often bypass the docs and choose to search on Google or Stackoverflow. They skim the text on the documentation pages but they don’t take the time to consider those docs in depth. Users will leave the documentation and try to find an exact solution on the fly.
This is not the desired user behavior on a documentation site.
As documentation pages are comprehensive instructions, they are not suitable for finding solutions quickly. And reading a book-long documentation does not fit into a developer’s workflow.
Summary: Documentation usually focuses on narrative how-tos, but this kind of documentation is the lowest-performing model.
2. Provide quick solutions and example code in documentation - what developers actually need
Developers look for:
- solutions to fix a problem,
- code that demonstrates how to build from scratch.
What they don’t need:
- stories,
- beautiful narrative around the code.
In the middle of the workflow - when a developer usually needs information - we should reduce the friction to make the documentation usable.
Based on Twilio’s research, code should always come first.
The code is why developers come to the site, therefore it has to be available as easily and quickly as possible. Long narratives don’t provide the executable solutions the devs are looking for. Stories shine in blog posts and marketing copy, because users read this kind of content not for finding solutions but for getting a better understanding and to find application examples of a product.
Therefore the aim is to build a platform for documentation that:
- shows code first,
- allows documentation teams to collaborate with the portal’s users.
3. Design effective How To Pages/Tutorials
How To pages must show code first and must harmonise with the developers’ workflow. How to achieve this?
The easiest way to understand code is to sit next to the developer who wrote it and learn from “the source”, that’s how we learn the fastest. The aim is to create the same experience through documentation. To do so, page hierarchy must be obvious with clean actions that show the user what they should do next. Besides that, code needs to be the narrative. Arranged this way, the documentation provides solid, easily adaptable solutions and frictionless onboarding experience for the developers. Tutorials made with this approach are scalable and deployable use case applications, not theoretical or abstract examples. That is the reason why tutorials of Twilio now consist of an integrated developer environment (IDE), code, and nothing else.
Twilio’s research provides data about the completion rates of tutorials as well:
- The completion rate of a tutorial is thirty percent higher if the code demonstrated in the first step is less than 20 lines. Code comes first but only the most important part of it.
- The completion rate also increased with twelve percent when the team minimised the amount of copy. The less words, the higher the completion rate.
4. Choose an extendable platform for your documentation
There is no one-size-fits-all platform for developer portals because requirements will be very different depending on your business model, your API, and the communities your API targets.
For example, Twilio built their platform with Wagtail on top of Django which is a Python-based framework. Basically, they used a framework on top of another framework to build a website. They did so because they needed a highly customizable, flexible solution.
This is the same reason why we think Drupal is such a great platform for developer portals: out of the box you get a powerful CMS that integrates with numerous services. To be sustainable in the long run, APIs need to adapt to the business needs of the organisations that build them. That might mean you will have to significantly change your documentation portal throughout its lifetime. There is something to be said for static sites, and their simplicity, especially if you just want to publish your API reference. But if APIs are a key resource for your business, you will need a flexible platform to execute and adapt your business strategies.
5. Add useful features to your documentation
Small tweaks can improve the overall developer experience of your portal.
- The possibility to switch between dark and light design might seem marginal. It is a handy solution that makes reading comfortable for the developers who often work in the dark.
- If your documentation site has insite search, users don’t have to leave your portal to find answers.
- Filters can simplify the searching process. Product, language and platform filters provide improved search results.
We are doing research about developer portals. If you are interested in our findings, subscribe to mailing list.
Do you have questions or further examples? Share your thoughts in the comment section below. We would love to get your feedback.
