Learn the Knowledge Base Best Practices from Twilio’s Developer Portal

Twilio is an API (Application Programming Interface) for Messaging, Voice, Video, and Authentication.

This means Twilio helps companies to deliver a variety of communications services over a web connection – an approach that has many advantages over developing in-house solutions.

Twilio would typically used as part of another company’s technology stack rather than as a service in itself. This presents unique opportunities for Twilio to use its documentation as marketing as well as for learning.

We’ve already included Twilio’s knowledge base in our run-through of 8 top SaaS knowledge bases. Now we’ll do an in-depth tear down of its knowledge base and learn some of the knowledge base best practices.

Introduction to Twilio

Twilio’s software is Platform as a Service (PaaS) which means it delivers core parts of a company’s technological infrastructure through the cloud.

Documentation is a key part of its strategy in a market traditionally dominated by telecom giants which are typically against any innovative market adoption of their services.

As a result of their strategy, Twilio is now a well-known brand in the technology sector. The company is classed as a tech unicorn and it has raised more than $216 million in 11 funding rounds.

Twilio also transcends a number of traditional industry categories, which makes its documentation even more interesting.

Twilio is business-to-business (B2B) so it needs to appeal to whole teams or even large companies with a significant budget to invest. The company’s business model is also business-to-developer (B2D). This means Twilio must also appeal to the individual developers actively working with its system.

Twilio’s knowledge base

The Twilio knowledge base is labelled on the main website navigation as “Docs & Tools”. This highlights the interactive nature of their knowledge base software, which is a practical resource as well as a learning resource.

Twilio’s knowledge base aimed at developers and particularly those of SaaS (Software as a Service) applications. Their product suite and the system has been designed for companies interested in outsourcing their communications infrastructure to help them scale potentially infinitely.

As a result, Twilio’s product docs are highly technical and always a huge work in progress. The knowledge base basically a product in itself and the target end users are developers – though these may not be the primary customers.

Twilio treats its developer users as humans – rather than robots.

Homepage

Twilio uses a slightly unusual format for its docs in that it uses a large hero section and then a list of the main sections. They’re also pushing a subscription to Twilio as soon as you arrive at the knowledge base, further suggesting they use their docs as marketing.

It’s about funnelling users into the right section at this point and organised by product rather than the type of documentation. Unlike Stripe, Twilio does not use internal names for their products but instead calls them something descriptive.

It’s minimalist but effective. The complexity of the Twilio documentation is only revealed once you click on a category.

Create a stunning landing page for your documentation website.

Start the Free Trial

Developer Advocacy

Once you dive into the Twilio’s company knowledge base, you realise that the Twilio docs are extremely thorough.

Thoroughness of docs is a key concern of developers, 83% of whom say documentation is the primary way they learn about new technologies (Stack Overflow Developer Survey 2018).

And developer advocacy is a core part of the Twilio brand. If developers are enthusiastic about the Twilio docs, then this promotes the overall brand and builds trust. Developers will recommend using Twilio to their friends.

So for PaaS and SaaS companies aimed directly at developers, community-building is a core priority.

And that’s where documentation comes in extremely handy. Although Twilio’s core audience may be used to wading through heavy docs, the content is organised so as not to seem overwhelming at first. This does not mean it lacks depth.

Interactive API calls are a key feature of Twilio and they can be performed in multiple programming languages with a click of a button.

You can toggle between different programming languages to get started with their Programmable SMS product. The interface is thoughtfully designed and visually appealing to encourage users to give it a try.

In developer documentation especially, documentation is always a form of marketing for your product.

Use Cases

For non-developers, however, it may be hard to understand what Twilio’s platform does from the outset since it is an API service. It usually integrates with other company’s technology stacks, so you have probably used Twilio’s services many times without realising.

Twilio cleverly takes advantage of the very fine line between documentation and marketing to appeal to all of its customers, regardless of the job role.

It has provided handy use cases on its main website to showcase Twilio’s functionality. This type of content provides some context for a service that may otherwise tend to seem quite abstract at first glance.

It all comes down to thinking about your audience, who may be divided into different groups.

While developers might also benefit from reading example use cases, CTOs (Chief Technology Officers), startup founders, CEOs and product managers will also gain vital understanding from customer case studies.

Twilio is asking for such a huge investment from its customers, who will be outsourcing whole sections of their technological architecture to an unknown team. Reliability and transparency is key to Twilio’s documentation and part of how the company has become so successful in its industry.

It reflects back on how Twilio’s docs are practical and hands on. The focus is on working code examples and API calls that showcase the service in real-time.

Twilio even links to the documentation from the use cases, joining its content up for a holistic marketing and documentation experience.

Visual Design & Layout

Visual design is especially important in developer portals since the documentation gives you a good idea of what it will be like to work with the Twilio platform.

Twilio has designed its knowledge base systems in the spirit of the Stripe docs. Focus on achieving clarity with a modern, sleek interface and densely populated but not cluttered.

Customize your documentation design and layout to suit your brand color and design.

Request a Demo

The dark colour scheme with blue as the main colour promotes a feeling of calm – which most people need when they’re working with APIs. it’s part of the Twilio brand but also conveys a sense of gravitas and importance – exactly what you want for communications infrastructure.

It’s effective but still distinctive. The Twilio visual brand is instantly recognisable.

The code interactivity is also an important element of the design since Twilio developers can play around with the API right from internal knowledge base to any customer facing software. They can get up and running right away and test their software easily.

Brand Voice

Unlike its visual brand, Twilio keeps its personal brand tone and voice to a minimum in its knowledge base.

The information contained in its online knowledge base is very technical, and as a result, it doesn’t reveal any personality between the Twilio brand.

As is typical for highly technical documentation, Twilio’s brand voice is neutral and to-the-point. There is no room for copywriting flair in the API documentation.

Directness is very important in technical documentation. You don’t want your company’s agenda to get in the way of developers getting started with or troubleshooting your technology.

Information Architecture/Navigation

Once you actually hit the docs after the homepage the navigation is a different story. Instead of being hit with a range of products, you are funnelled between documentation types.

Twilio divides its docs into five categories in its top knowledge base navigation which correspond to the main site footer:

• Quickstarts
• Tutorials
• API reference
• Helper Libraries
• API status

Twilio has used Information Architecture for its docs audience with expertise and flair. The audience has a good idea of what the docs contain based on looking at visual cues like navigation options and interlinking.

Sometimes the navigation for its knowledge is a little confusing because Twilio is providing complex information for so many products – but overall it’s easy to reorient yourself.

Taxonomy

As for as taxonomies go, Twilio is smashing it. Your taxonomy is basically your naming conventions for your knowledge base categories and content.

Based on the taxonomy, you can immediately see the range of documentation Twilio provides and developers will be relatively familiar with this category terminology.

In terms of content names in their taxonomy, Twilio is using action-oriented content titles to be as descriptive as possible. It’s much better to stay away from idiosyncratic names as you want to reveal as much information as possible.

Twilio’s core users won’t just be skimming the knowledge base but rather going in-depth as an integral part of their workflow. Simplicity in naming (which is not easy to achieve) makes their job easier.

Findability

The left-hand navigation for Twilio’s knowledge base does change depending on which section you are in. To counteract this, it always has the same top navigation with broad overview categories.

Anchoring the navigation on the left-hand side is normally a better way to improve efficiency in your documentation.

Users can see the whole structure of your knowledge base at all times and quickly navigate around as they accomplish tasks. Revealing the structure empowers your user to take charge of their own learning.

Twilio has had to adapt due to the complexity of its documentation.

Search Function

Twilio doesn’t overly rely on the search function or force users to follow a pre-defined path. Nevertheless, the search function on its knowledge base is highly sophisticated.

The results even contain interactive code examples, which possibly means they have the most impressive search tool ever. Using colour and shape to break up the results also adds to the User Experience in this instance.

Still using the old search feature to find the relevant information? Start switching to an interactive AI-based search!

Signup to Know More

Code Snippets

As we’ve just mentioned, Twilio is a big fan of interactive code and making live test API calls.

The content pages are broken down well to make the code snippets more visually appealing. Overall, the interface is reminiscent of a code editor such as Code Pen and is fun to use.

These kinds of knowledge bases must be excellent at dealing with documentation for multiple programming languages. They have to repeat most of their docs for PHP, .NET, Java, Node.js, Python and Ruby, which results in a lot of documentation to maintain.

The fact that you can toggle between the different languages makes the presentation far more user-friendly than showing them all on the same page.

Having a sophisticated and visual tagging system in the left-hand sidebar helps Twilio’s users to browse the content by the programming language, product or platform. They also have to account for different Operating Systems (Windows, Mac, Linux) which is all taken care of tags and toggles.

Going the Extra Mile

API documentation can be notoriously dry but it’s absolutely crucial for a successful API.

On his blog Docs by Design focusing on API documentation, academic and technical writer Bob Watson talks about how essential good docs are. Bob talks about treating your documentation as a product with its own distinct customer base.

Twilio Quest is their very own game designed to onboard potential customers into the Twilio platform. This is a unique and interesting way to gamify their docs.

Twilio also has the resources to devote to hosting its own customer/developer-focused conference called Signal:

This shows how fully invested in their customer and user base they are by fostering the community.

Still looking for best in class Documentation portal? Document360 can be the right choice.

Get Started Now

Error Messages

Error messages are also an integral part of your documentation, but you wouldn’t usually include them your knowledge base. Twilio is different.

Twilio has included common error message strings from its API in the documentation help its users understand what has gone wrong with the platform.

For example:

Twilio publishes an entire Error and Warning Directory, including possible causes that have thrown the error – even better – possible solutions. This helps them keep their actual error messages shorter but provides more information for those who need it.

User Experience

The first principle of exceptional User Experience defined as:

“The first requirement for an exemplary user experience is to meet the exact needs of the customer, without fuss or bother.” (Nielsen Norman Group)

Overall Twilio’s User Experience is exceptional. NN Group goes on to say that multiple disciplines must merge to create this type of UX, including marketing, engineering, and design. That’s exactly what Twilio has done.

Instead of viewing their docs as a silo which belongs to one team, Twilio has organised the full might of its company behind the docs. This pays off with its exceptional UX.

The needs of the customer, in this case, is firstly to understand the Twilio platform, and secondly (but more importantly) to successfully onboard with Twilio.

Implement these best practices to your Knowledge base and keep your documentation fresh and clean to your customers.

Signup to Get Started

Top Take-away Tips

Follow Twilio’s example and use the best knowledge base format for your specific audience.

Even if you’re not publishing API documentation, you can still tailor your knowledge base to delight your users.

Here’s a wrap up of top tips we’ve learned from Twilio’s docs:

• Dare to be different – consider developing a game to onboard your customers or making your code examples interactive
• Cater to your user – if your audience is not the one parting with the money, that doesn’t matter
• Keep your writing style direct and to-the-point – don’t annoy your developer users with copywriting techniques
• Reveal your navigation – give your users a better idea of the overall Information Architecture in your docs