Documentation that powers API strategy

Focusing on the tasks that developers can accomplish with a services, rather than the services itself, can be an impactful tool for boosting your API strategy. In this DevRelCon London 2017 talk, Scott Stroud, Lead User Experience Strategist at National Public Radio (NPR), talks about the methods his team have used to redesign their developer centre to help developers and partners build new products for their army of listeners.

Transcript

First of all, I’d like to encourage all of you to do something that is uncomfortable today, every day. I learned about Sarah’s inability to come here, about a week ago, so I’m giving her talk, but I’ve added some information. Actually, some inspiration from her talk that really affects how I do my work as a UX strategist at NPR. So, my job is I think a lot about our ecosystem of products. So, how an audience member might, throughout their day, from morning to night, weekdays, weekends, use all of our products. And I’ve actually recently developed a model for how we might think about that, which involves the same kind of abstraction that developers and dev rel folks will do, and folks right in documentation to abstract services for something like an API.

Building outcomes

So, how many of you are familiar with NPR? Great. Okay. So, NPR, our mission… We are a mission-driven organisation. So, our mission is to work in partnership with our Member Stations. We have stations throughout the country to create a more informed public. So, that’s a pretty big task, right? In the era of fake news, and, you know, we definitely arch our challenges to give people a deeper understanding of events, ideas, and cultures. So, there are tons of stations throughout United States, and we have bureaus reporting throughout the world. And so, this is the part that I’ve added to Sarah’s presentation, which is that I’ve realised that what we do, and this could apply to any of you, so feel free to use this model. We craft experiences to deliver outcomes to the audience. So, an outcome is not opening an app and using an app, right? An outcome is something like catching up with the news, having a sense of place, connecting with someone. That’s what I mean when I’m talking about an outcome. And all of those outcomes support our mission of creating a more informed public.

And so, we craft experiences. Well, what is an experience? An experience is something that you can know with your senses. So, you can hear something, you see something, you feel something. So, an experience might be listening to the news, or skimming the news, or watching a video. So, I’m not telling you where that experience happens, on what product, or what platform, or in an app, or on a website, or on a smart speaker. So, those are experiences. So, you know, you think about the sound of Audie Cornish’s voice telling a story. That’s…can be experienced, but at NPR, we think about inclusive design, which means that if you are deaf, you cannot hear Audie’s voice, so therefore, your ability to have a sense of place in the stories she’s telling would need to come through, perhaps, reading that story. So the experience, in that case, would be reading, not listening.

Abstracting experience

So, now is the next level which is products. So, we build products on multiple platforms to deliver those experiences. So, a product might be an app, it might be something else for the audience. So, an example is our web…responsive website. This is our news app, NPR News, and actually, this is a redesign of this app so you could expect this in the next few months. And then, this is the NPR One app. Has anyone heard of NPR One in the audience? Okay. We got one person.

So, NPR One is a fairly new product that essentially delivers personalised listening. So, you download the app, you log in. It starts to learn, not necessarily what you like, but it learns how to give you a flow of stories, both news and podcasts, and all kinds of things so that you feel like it understands you, but it also feels like it has the DNA of public radio. It sounds like what you would hear when you turn on the radio, but you can control it. You can press play, you can start it, you can skip things, you can mark things as interesting, so it starts to understand your signals. And you can also look things up and see what we recommend and all kinds of things like that. And it includes podcasts and other audio from all over, not just from NPR, and from public radio.

So, we also abstract our experiences so developers and partners might build new products for our audience. So, NPR One, I mentioned that it’s an app. Well, it’s also a service, and an experience that is one people, like, you all didn’t know that this experience even existed of this sort of personalised listening. So, we wanna bring it to as many places as people are, so whether that’s your Xbox, or whether it’s, you know, your phone, or Apple TV, or whatever. So, here’s some examples of…on the left, the Xbox, and Android Auto, and Samsung Gear.

And, this is the Developer Center. So, Sarah worked on a project to redesign this several months ago, and what the message she wanted to deliver to you is what she learned, and a strategy, and a workflow for how to work with your teams, your developers, your product owners, your UX folks to develop…

“We care about developers as we care about our audience”

So, why do we need this? Well, we offer what we’re calling 21st-century public radio. So, this is the new thing, and what we’ve decided is this. We’re putting… We’re essentially saying that the APIs we make available, the most important thing we think we could do is make this new form of listening available to our audience, right? So, we’re not… I’ve been around at NPR since about 2006 when we first launched our public APIs, and that focused on stories, and audio, you know, for particular stories, and list of things, and topics, where is this is really focused on this brand new form of listening that includes authentication, that includes these signals so that we can start to know the audience better, and them adapt to what they need.

So, we care about developers as we care about our audience, which means the methods we’ve used to redesign this site, and the methods that we think about our developer partners is the same as we would as we think about our listeners, and the folks that come to our website, or use our apps. So, I talked about the experiences and the idea that listening to radio was an experience. Well, in my mind, the developers, the experience is the act of creating, so the flow that you might get yourself into while listening to public radio, the flow that you might get into while coding is an experience.

Let’s take an example of a coffee shop. So, how many of you like pour-over coffee? Fans of pour-over coffee? So, I’m not gonna say it’s the best way to make coffee, but it is a way in which you can maybe get a higher quality experience of drinking coffee. So, you gonna think about, like our audience, our listeners, the coffee drinkers, right? In this case, the person who is crafting the coffee, making the pour-over coffee, you could think of is a developer. Well, let’s say that you wanted to get your, say, you also roasted coffee, and you wanted to get your coffee out there in the world. Well, you wanna make sure that the developers out there, the coffee makers out there are doing the methods to make sure that experience. So, it’s not like, you know, your beans can be used anywhere to make coffee. We wanna make sure that you’re crafting the best experience possible.

So, the products that we think of are APIs and documentation. So, here’s an example, if I know was new to this, and, you know, I found out about your coffee beans, and these are instructions I found that you made available, but they’re about French press, and they’re about, you know, roasting, and all things. You know, they’re true information, but it’s not necessarily related to the task and the task orientation I need as a developer in order to build the right thing. So, we wanna shift the focus from what the endpoints can provide to what I, as a developer, can do as an API.

And so, before we do anything, really understanding as an organisation, why are we making this service publicly available? Like I said, it’s like the guy doing the pour-over who, you know, is incredibly skilled at his job. He understands how to weigh everything, how to measure everything, how to release the gas in the coffee, all those kind of things, and what task might this person wanna accomplish? And so, we build relationships throughout our organisation, as we think about building this documentation, so it’s not just the technical writers talking to developers. Because, our developers are using some of our internal APIs, right? They don’t even necessarily have the mindset of someone who is out there, you know, working for another partner or someone else trying to deliver the experience that we want them to deliver on our new product.

Building around developer objectives

So, we might define personas. So, this is a matrix of the different things you might think about as you develop personas for your audience. If you’ve attended some of the other talks today, you’ve learned about personas, if you didn’t know what they already are. So, we think about, you know, how we can, you know, really think about the person out there who may understand what NPR is, that may think about live streaming, and may think about stories, and may think about text, and they don’t even know this experience of personalised radio exists so we have to help them understand what that is, and help them understand the type of experience we want to give them.

So, we did research. We met with folks who are in this position and we got, you know, very detailed information about what wasn’t working about the old documentation, and some of the things we found were the site is hard to navigate, it’s difficult to understand our priced authentication. We have this thing called ratings where we learn about how you interact with audio, whether you skip it, whether you listen to it all the way through, whether you listen to first 15 seconds of it. All of those are signals that help us improve your experience. So, a developer has to understand why that’s important to the end experience.

And then, we identify and prioritise tasks. We think about the common task that the developer might be trying to do and structure the documentation around those tasks. And, some of our takeaways for a redesign is that we should highlight those prioritised tasks, we should present the information according to the order of operations, shallow navigation, link to other checklists, and other links to other more important things that may not be needed for that general impression of what we’re doing, and what the high-quality experience we want to offer our audience.

So, we still provide, you know, the standard, the API reference docs. And, once we… Sarah and her team, including Vince Farquharson, who’s on the design team at NPR, someone I work closely with. This is what we found. It’s we wanted to collect data to help us understand, you know, whether or not we succeeded with this. And so, we got good feedback about that, and we continue to improve our docs. So, the benefits of doing this scoping. In public radio, we have incredibly limited resources. Rapid prototyping helps us to lower the cost, to explore, you know, and fail sometimes, at things we think might work. Faster turnaround on QA. So, some of the folks, when you think about our folks doing QA both internally, when we… You know, we often go through process of looking at the products that outside partners have developed, and evaluating, and giving them feedback. So, we’re talking about an ecosystem of developers and partners that’s within NPR or outside NPR that includes, stations often. And, the end result is we want a high-quality user experience from listeners across these platforms.

And so, we really can also apply this kind of thinking outside of just the docs or the developer center, or the site, which is, you know, things like a developer newsletter, thinking about our app checklist, how we conduct surveys, who are we talking to, what is our audience for things like surveys, even conference calls and emails directly with developers, including our partners, understanding their perspective, and understand what they might know. We’ve had a developer who took our information. We thought they’re gonna be delivering this personalised listening service, a new product to deliver NPR One’s personalised listening, and we realised that they had produced something that played live streams. They completely missed the point of what we’re trying to do with the old documentation.

So, back to the coffee example. So, in this kind of a world, if we’re trying to develop this kind of documentation of how to create pour-over coffee, we’re focusing on things like, you know, you need to place a filter in the cone, you need to grind to a certain coarseness. There’s much more beyond this, obviously. You know, the inspiration from a site like, you know, one of the coffee producers like Blue Bottle or Stumptown. They actually do this really well on their sites. They provide this kind of documentation. So, when your inspiration is you think about creating your docs, you might even look at completely outside the world of code and APIs, and look to other places that are trying to, you know, inspire folks creating things in the world to not only just create the thing that you want them to create, but actually do with the level of quality that you actually want because your brand is on the line, and the experience. And, in our case, we wanted to created more informed users. In their case, they might want to create, you know, and hook people on coffee, and saturate the world.

So, I actually worked with Sarah on this. I’m thinking about a checklist, and there’s a URL up here where you can get this presentation, so you can use this checklist if you like for how this might work in your organisations or workflow. Identifying the goals and priorities, how to define the steps in defining personas and tasks, describing the tasks and the workflow in detail, and then the type of matrix you might create. If you were to create personas and then share these personas with your team, thinking about the role they might have in an organisation, the goals that particular persona is trying to accomplish. The behaviours, you know, how do they feel, how do they go about this, what’s their problem-solving process? And the attitudes, the how they feel, how they perceive themselves.

Can you sort of infect those folks with the same internal passion we have within our organisation for creating a more informed public? Can we help them see that they’re actually part of that mission that so someone in the public or someone who’s a partner who is a creator, who is a maker can actually have the same kind of impact that we feel as employees, and folks at NPR? So, I’ve tried to keep this short so that we could catch up on time. If you have any questions, please feel free to grab me afterwards, and use this URL if you’d like to use those checklists. Thanks.