(You can find the slides from the presentation here.) Developer experience is an extension of general User Experience, which emphasizes the developer, and their experiences working your API. A good API developer experience goes beyond technical writing. It is about providing all the right resources that help your end consumers successfully integrate and work with your API.
The role of documentation in DX
A well designed developer experience has API documentation at the center of it. API documentation is the information that is required to successfully consume and integrate with an API. This would be in the form of technical writing, code samples and examples for better understanding how to consume an API. According to SmartBear’s 2016 State of API Report, 75% of organizations that develop APIs now have a formal documentation process. 46% say it is a high priority for their organization. Concise and clear documentation — which allows your API consumers to adopt it into their application quickly — is no longer optional for organizations that want to drive adoption of their APIs.
Good documentation isn’t an easy task
For a lot of API teams, documentation is still a tedious and time consuming task. This is especially true for teams that rely on static documentation that is manually updated with every release of new versions of your API. But there have also been some significant changes in the ways organizations document their APIs. Nowhere are these changes more evident than in the widespread adoption of API description formats, like Swagger. Swagger is an open source API framework that allows developers and teams to design, build, document and consume RESTful web services. One of the biggest reasons why the Swagger framework has gained such massive adoption is the ability to generate interactive documentation. This documentation allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. This auto-generated documentation is a central resource that your development team can customize, and build on to create a more comprehensive user manual for working with your API.
Adding Swagger to your documentation
Whether you’re new to Swagger, or have already been using the framework for API design, there’s a good chance you still have questions about how to improve your API documentation. Creating API documentation your consumers will love can take some work, but the investment will have a significant payoff in the form of a great developer experience, easier implementation, and improved adoption of your API. This month we hosted a free training on API documentation, API Developer Experience: Why it Matters, and How Documenting Your API with Swagger Can Help. We covered good developer experience in detail, focusing on why and how to provide an optimal experience for developers using your API. We will also cover how Swagger has changed the API design and documentation landscape, and finally show some good practices for API documentation using Swagger in SwaggerHub’s integrated API development platform. Things to expect in this webinar:
- What is Developer Experience (DX)?
- What does it mean for an API to have good DX?
- API documentation in the context of good DX?
- An introduction to the Swagger framework
- Designing APIs from a usability perspective using Swagger and SwaggerHub