Analyzing doc portals by looking at developer journeys -- recommended podcast episode from Cherryleaf
You can listen to the Cherryleaf episode here: Podcast 104: Fixing broken developer portals or through the player embedded below:
The Cherryleaf post also has a transcript of the podcast.
Ellis says that when Bob Watson and Emmelyn Wang served as judges for the API Developer Portal awards, they based their criteria how well the API documentation served the developer’s journey. Ellis explains:
Imagine you’re a developer from the start wanting to get a response from the API. Go through and look at all the steps that need to be taken that are advised from the site. So what needs to happen and create what’s called a friction log. And in your friction log, you can have a column for all of those steps that are going to happen, and then another column where you can document your experience of going through their steps.
Was the step of signing up easy, or was it difficult?
What’s the step of understanding what the product do clear and understandable?
And if there are any issues or problems, in terms of the information not being clear or being missing.
Then you write that down in that column for that particular step, and then the column next to it you can then record down any immediate thoughts on how that problem can be fixed.
So you go down through the journey at each point identifying any issues with navigation, accessibility, comprehension.
I like this approach. It’s given me food for thought given my previous articles on Measuring progress against documentation quality goals. My approach to measuring documentation quality was to analyze an API doc portal against quality measures that include findability, accuracy, relevance, clarity, completeness, and readability (see Quality checklist for API documentation.
However, I think that another approach, perhaps a better one, might be to analyze documentation quality against the developer journey, as Ellis and others explain. This developer-journey approach would require you to first define that developer journey, though. And understanding that journey might not be straightforward — there might be many different developer journeys once developers get past the initial steps of signing up and authorizing an API call.
One common analogy used with developer docs is that an API is like a cupboard full of ingredients — you provide the ingredients, and the developer figures out what recipe to make. In this analogy, the “chef’s journey” might include getting out a mixing bowl, turning on the oven, setting a timer, etc. But the number of other tasks in the chef’s journey would depend on the particular recipe they’re following, which could be one of hundreds.
Not all API products have hundreds of journeys, but my point is that there’s some flexibility here. I touched upon this briefly in Checklist of different types of API docs. For sure, I think that knowing and understanding the developer journey is central to shaping a documentation portal. But at the same time, pinning down the developer journey is not always easy and might require a lot of research into developer profiles, tasks, contexts, business domains, and friction points. This is certainly something that should be on our minds but which we might overlook if we assume that the product development team has already done this research, and we are merely documenting a product that fits that journey.
Perhaps in some upcoming articles in the metrics and measurement section, I’ll try to provide a more formal approach to analyzing developer portals by looking at the developer journey. It’s hard to say how feasible this approach is without more hands-on experience trying it out. At Amazon, I once wrote a 35 page article describing the developer journey in building a Fire TV app for both Amazon and Roku, and it was one of the most illuminating articles I’d ever written (internal only, unfortunately). Knowing the key points in the developer journey, if only at a high level, made it easier to shape the general trajectory of the documentation.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.