Start with the tasks, not the endpoints¶
Description
Last spring, as I approached reworking the information architecture of the NPR One Developer Center, I started by interviewing several of our partner developers to find out what pain points they encountered when developing on our platform.
Overwhelmingly, the responses included complaints about confusing site navigation and frustration around having to search multiple pages to string together the necessary information to implement features. After considering this feedback, we redesigned the documentation site to focus on information needed to complete a desired task, and while we still provide endpoint reference documentation, my focus now is to start from thinking about what a developer is trying to accomplish, rather than what data an endpoint is capable of providing. Essentially, the focus of the docs shifted away from what the API can do, towards what “I”, as the developer, can do with this API.
Taking a task-oriented approach allowed us to reorganize and revise our content in a way that has significantly shortened our onboarding process for partner developers, shortening the app verification process and time-to-market, and most importantly allows us to better collaborate with our partners to develop exciting new experiences for NPR listeners. For those who work on documenting hypermedia APIs, this can be a particularly useful approach, since these services tend to have fewer specific endpoints, and the documentation needs to focus much more on how the client can successfully navigate links to accomplish the desired task. In this 30-minute talk, I' ll discuss how you can successfully integrate this approach to your workflow when considering everything from overall information architecture, to deciding which content assets to prioritize, to refining the tone used throughout your developer communications.
- Conference: Write the Docs NA
- Year: 2017
About the speaker
