Twillio announced this week a new form of documentation for their API. Abraham Maslow once said “If you only have a hammer, you tend to see every problem as a nail.”, and the developers at Twillio have looked at the issue of how to describe their API as something that can requires a more application-like solution. Twillio has developed step-by-step tutorials that provide an annotated walkthrough explaining what each significant chunk of code does.
With Tutorials, we tried to reverse this relationship between text and code. Code shouldn’t illustrate the narrative – code should be the narrative… 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 in the upper right corner. You can get the app’s full history browsing the commits on GitHub.
This view highlights an attitude towards code examples in API documentation. Are they there to act as tutorials to teach developers how to code? Are they illustrations similar to figures in books? Are they handy timesavers for developers wanting to start using the API?
Twillio’s view seems to be that the code should be, in many ways, self-explanatory. We suspect the tutorials will end up complementing, rather than replacing the API reference documentation.
What do you think?
Ellis, thanks for bringing this up. The success of the tutorials will depend on how well they meet the expectations of the target audience. You got to the heart of the matter with your questions about the role of code examples.
For me, the code examples are handy timesavers. But when it comes to programming I’m strictly an amateur — not the true target audience at all. So I can’t really answer your questions and I don’t know how the tutorials will be received. As always, the proof is in the pudding.
Thanks Larry
Absolutely. Even otherwise, a product knowledgebase is a product in itself because we plan its structure, usability, branding, and effectiveness in the same way as we do it for a product.