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?