--- title: "Podcast 105. What are the most common problems organisations make with developer portals and API documentation?" id: "15487" type: "post" slug: "podcast-105-what-are-the-most-common-problems-organisations-make-with-developer-portals-and-api-documentation" published_at: "2021-03-18T07:07:48+00:00" modified_at: "2021-03-18T12:04:39+00:00" url: "https://www.cherryleaf.com/2021/03/podcast-105-what-are-the-most-common-problems-organisations-make-with-developer-portals-and-api-documentation/" markdown_url: "https://www.cherryleaf.com/2021/03/podcast-105-what-are-the-most-common-problems-organisations-make-with-developer-portals-and-api-documentation.md" excerpt: "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..." taxonomy_category: - "API" - "podcast" taxonomy_post_tag: - "APIs" - "developer portals" - "podcast" --- 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. ### Share this: - [Share on Facebook (Opens in new window) Facebook](https://www.cherryleaf.com/2021/03/podcast-105-what-are-the-most-common-problems-organisations-make-with-developer-portals-and-api-documentation/?share=facebook) - [Share on LinkedIn (Opens in new window) LinkedIn](https://www.cherryleaf.com/2021/03/podcast-105-what-are-the-most-common-problems-organisations-make-with-developer-portals-and-api-documentation/?share=linkedin) - [Share on WhatsApp (Opens in new window) WhatsApp](https://www.cherryleaf.com/2021/03/podcast-105-what-are-the-most-common-problems-organisations-make-with-developer-portals-and-api-documentation/?share=jetpack-whatsapp) - [Share on Bluesky (Opens in new window) Bluesky](https://www.cherryleaf.com/2021/03/podcast-105-what-are-the-most-common-problems-organisations-make-with-developer-portals-and-api-documentation/?share=bluesky) - ### *Related* ### Leave a Reply[Cancel reply](/2021/03/podcast-105-what-are-the-most-common-problems-organisations-make-with-developer-portals-and-api-documentation/#respond) This site uses Akismet to reduce spam. [Learn how your comment data is processed.](https://akismet.com/privacy/) #### Previous post [Podcast 104: Fixing broken developer portals](https://www.cherryleaf.com/2021/03/podcast-104-fixing-broken-developer-portals/) #### Next post [Screenshots from the Mathspeak project](https://www.cherryleaf.com/2021/03/screenshots-from-the-mathspeak-project/) #### Browse posts by month Browse posts by month Select Month August 2026 (5) July 2026 (7) June 2026 (14) May 2026 (8) April 2026 (6) March 2026 (14) February 2026 (9) January 2026 (9) December 2025 (7) November 2025 (9) October 2025 (10) September 2025 (7) August 2025 (6) July 2025 (1) June 2025 (3) May 2025 (2) April 2025 (5) March 2025 (3) February 2025 (3) January 2025 (2) November 2024 (8) October 2024 (3) September 2024 (2) August 2024 (3) July 2024 (4) June 2024 (1) May 2024 (2) April 2024 (4) March 2024 (1) February 2024 (2) January 2024 (1) December 2023 (2) November 2023 (9) October 2023 (8) September 2023 (5) August 2023 (3) July 2023 (1) June 2023 (1) May 2023 (2) April 2023 (3) March 2023 (2) January 2023 (2) December 2022 (4) November 2022 (1) October 2022 (1) September 2022 (1) August 2022 (1) July 2022 (1) June 2022 (1) May 2022 (2) April 2022 (1) March 2022 (1) February 2022 (1) January 2022 (2) December 2021 (1) November 2021 (2) October 2021 (1) August 2021 (1) July 2021 (2) June 2021 (3) May 2021 (5) April 2021 (3) March 2021 (3) February 2021 (1) January 2021 (2) December 2020 (4) November 2020 (4) August 2020 (3) February 2020 (3) January 2020 (1) November 2019 (3) October 2019 (1) September 2019 (1) August 2019 (3) July 2019 (2) June 2019 (3) May 2019 (4) April 2019 (1) November 2018 (2) October 2018 (1) July 2018 (2) June 2018 (4) May 2018 (2) April 2018 (3) March 2018 (4) February 2018 (2) January 2018 (3) December 2017 (2) October 2017 (3) September 2017 (1) August 2017 (3) July 2017 (2) June 2017 (7) May 2017 (4) April 2017 (5) March 2017 (1) February 2017 (7) January 2017 (1) December 2016 (3) November 2016 (4) October 2016 (1) September 2016 (5) July 2016 (1) June 2016 (3) May 2016 (1) April 2016 (2) February 2016 (2) January 2016 (5) December 2015 (1) November 2015 (4) October 2015 (2) August 2015 (1) July 2015 (1) June 2015 (2) May 2015 (3) February 2015 (2) January 2015 (6) December 2014 (1) October 2014 (1) September 2014 (4) June 2014 (4) May 2014 (1) April 2014 (2) March 2014 (3) February 2014 (4) January 2014 (4) November 2013 (2) October 2013 (5) September 2013 (3) July 2013 (3) June 2013 (11) May 2013 (4) April 2013 (6) March 2013 (7) February 2013 (4) January 2013 (4) December 2012 (9) November 2012 (23) October 2012 (14) September 2012 (8) August 2012 (4) July 2012 (12) June 2012 (12) May 2012 (10) April 2012 (8) March 2012 (12) February 2012 (3) January 2012 (6) December 2011 (2) October 2011 (3) August 2011 (1) June 2011 (5) May 2011 (2) April 2011 (1) January 2011 (1) December 2010 (1) November 2010 (3) October 2010 (4) September 2010 (8) August 2010 (5) May 2010 (2) April 2010 (3) March 2010 (3) February 2010 (2) January 2010 (3) December 2009 (2) November 2009 (6) September 2009 (1) July 2009 (6) June 2009 (7) April 2009 (8) March 2009 (3) February 2009 (3) January 2009 (3) December 2008 (1) November 2008 (3) October 2008 (3) September 2008 (4) August 2008 (1) July 2008 (3) June 2008 (5) May 2008 (2) April 2008 (2) March 2008 (3) February 2008 (2) January 2008 (1) November 2007 (3) October 2007 (2) September 2007 (1) July 2007 (3) November 2006 (1) October 2006 (2) September 2006 (3) August 2006 (1) April 2006 (1) March 2006 (3) #### Browse posts by category