On social media, we asked “what are the most common problems organisations make with developer portals and API documentation?”
In this episode of the Cherryleaf Podcast, we look at the responses we received. We also discuss some of the other common mistakes that we’ve come across.
Transcript:
This is the Cherryleaf podcast.
Hello again, welcome to the Cherryleaf podcast I’m Ellis Pratt, one the directors at Cherryleaf.
In episode 104 of our podcast, we looked at fixing broken developer portals and I thought it would be good to expand on some of the common problems that there are with developer portal, so not so much looking at how to fix them, but what problems there are.
And that may help you in identifying whether there’s some issues with your developer portal if you have one, and recognise that there might be a need to make some changes.
So like we’ve done on some of the other episodes, we’ve put out a question on social media and asked others what their thoughts were.
And so on social media, I posted up the question:
What are the most common problems organisations make with developer portals and API documentation?
And I got a number of responses back. I’ll see if I can group them together and expand on some other areas that also can happen with these types of sites.
So one common theme was around examples.
And move the comments backwards from Deborah Barnard, who goes under the name Starfall projects on Twitter. And she said:
Lack of examples, or overly complicated examples (I get the marketing value of having a React demo, but for those of us not using React, it’s a pain)
And this is one of the common themes that developers want to see: an example from beginning to end. This is something that came up on one of the early podcasts that we did talking about the European Online Help Conference. One the presentations there, where there was a company who had created cookbooks to take a developer from the beginning to the end on one thing. That if there’s an example that takes somebody through, all of the stages from that, often developers can infer, work out.I should say how to do it in other situations. For other endpoints and so on.
So having examples that somebody can look at that enable the developer to get a result.
Very important and examples that just don’t exist.
To make that a lot more tricky, I think one of the challenges why organisations don’t have examples is that they are time consuming to create. You need technical skills often to create them. You need the ability to set things in the correct context, explaining why things need to happen in certain places and also they need to be maintained.
So we’ve got a client at the moment that is got a developer Portal and they have a Swagger file and they’re using an application to generate the API reference documentation. And with that application that they’re using, it’s generating code samples that can go with the documentation. Unfortunately, the code samples aren’t very good. And there are, apparently, a few bugs that mean that some of the lines are repeating themselves in the code samples. So if a developer were to use them as they were , they may not get three desired result. So what they’re having to do is to go in and either delete those examples or hand edit them to make them correct. Whenever the API gets updated, that process has to go through again.
And this links in with something else that Maiken Blok, who’s based in Denmark and who also helps contribute to Tekom Denmark. And she said:
Probably forgetting to update the documentation, so everybody knows what the different services and methods do.
And this is part of the challenge with developer documentation with API portals is they do get out of date as the APIs develop, as related technologies develop.
Then there is a need to keep the documentation maintained. It needs to be somebody’s role or at least or within a range of people’s roles that it’s updated and that they actually do that.
And this also came out with a comment from Dave Beaumont.
He said:
My biggest frustration comes even before portals and docs (although this might not help)
If you can do something in the app, but not via the API, it’s the most frustrating thing in the world
And on a similar theme, Emmelyn Wang from Amazon said about portals and API documentation that one of the biggest issues was not prioritising them as first–class citizens with the API itself and the related products.
Lornajane said:
With developer portals in particular I find that sometimes the content is grouped into “content types” rather than the topics that I’m looking for. I don’t know if you’re going to show me the thing I need in a tutorial, a guide, or something else. So then you end up using a search engine rather than the actual developer portal to find things.
Some recurring problems that we’ve found with these types of sites is around the information architecture, how it’s been designed. How information is being organised.
Among the common problems is there’s no central start point. Where do you start?
That it can be possible somebody could start in a number of different places and therefore the temptation is that you say you can start here. You can start there and you can end up with cognitive overload for the reader that they have too many choices.
And often there is a best path that you have an ideal path that you want somebody to go through a customer journey so often. Having it clear where somebody starts can make a big difference.
And linked with this is that where people navigate around the site to different areas. If they’re looking at the API catalogue to see what the APIs do, why you might want to use them, or signing up or looking at the reference documentation or the rate limits.
Other information is that there’s often a lack of a breadcrumb trail. Knowing where you are within the hierarchy, which branch of the tree that you’re on. And that can make things tricky for knowing where you won’t have to navigate to certain places.
And linked with that can be if people are within a sandbox environment or a production environment. There may be pages that may have the same title as in a public domain, but have slightly different information. So it’s not clear that you are looking at content specific to the sandbox or specific to the live environment, or information that’s there before you log in and have signed up to the sandbox or production areas.
Another common problem is that as APIs become more popular, so they are being used or looked at by people of a wide range of skills and abilities, some of whom may be looking at an API for the first time and the first API they look at is yours. So there’s a lot of common knowledge that may not be common to them now. It may not be, probably isn’t, appropriate if this audience is less than 10% of your audience to go into all of the details of how to do a particular thing. But one thing there should be is links to training information, or information provided by other people, or even Wikipedia articles, that helps them understand the context of the conceptual stuff that they need to be aware of, in order to be able to use this API.
So even just providing basic links, terms, concepts, that type of thing, having those available can make it easier, more accessible, to that nontechnical audience. And also going back to the comment from Lorna Jane, one of the problems is that a lot of developer portals aren’t based on an optimised user journey. Often, they are structured around organisational limitations within the organisation or the application’s limitations. And they force the structure of the site to be done in a certain way, in order for it to be published efficiently.
So you end up with a user trying to navigate around the issues within the organisation. So that you find that certain products are owned by different departments, and then placed on a portal and you have to in your guiding people away from the site.
And other APIs have certain limitations, or certain technologies that must be used, and these can cause challenges for the reader, for the user. And so you could end up with a lot of reference information and a lot of information about what the thing is, but often there’s a lack of what you might call task–based information: that the goal is to get a response out of the API, or to connect with a particular product. And so this need for cookbooks or task–based information of how to do something, rather than what it does, is often lacking within the content that’s provided.
We saw when we talked about the Developer Portal Awards, where the winner Mercedes-Benz has managed to connect the marketing material, the task–based material, and the reference material altogether so that you can understand with the different APIs and products that Mercedes-Benz offer for their cars, what it does, why you’d use it, how to use it, where to start, and that type of information.
And that is another common issue or problem that lack of basic copy you might say, or marketing information. What does this thing do? Why would I use it? When would I use it? What benefit is it to me to use this particular API and integrate this API into my product.
So we’ve actually covered quite a lot in a comparatively short space of time. Well, the most often mentioned one was this one around samples or examples, code samples, and other examples, to help people understand what to do or how to do things. And that’s probably the area where it’s the hardest or can be difficult for people to fix.
It’s the information that often developers want the most, probably the one where it makes sense to focus and see if you can fix that. And then the other one that seems to appear often Is this issue of being lost in all of the information that’s there to help people. Have a good navigation route, user journey from where they can start to completion.
Getting that developer journey, the information design, information structure right.
So these are classic, common problems, common issues with large websites, with help files, and the like. And API documentation, developer portals have similar issues, similar challenges to other types of content that’s available.
So this is the most common problems that we’ve come across. What other ones have you come across? Let us know. You can contact me by Twitter, ellispratt or email info at cherryleaf.com
Do let us know so that’s it for this episode of the Cherryleaf Podcast.
Thank you for listening.
Leave a Reply