Table of contents for the Transcript
General introduction [0:00-01:07], Jury Group - introduction [01:08-08:41], Aspect of developer portals that coming more into focus [08:42-15:43], Interactivity and solutions that used to be a novelty [15:44-20:32], Things that would be better to stop being standardly done [20:34-26:58], Advise on the future of API user experiences [26:59-35:22], Closing Thoughts [35:24-37:07], General Closure [37:08-37:32]
Back to the DevPortal Awards 2022 Jury Interview page »
Transcript
Jury Group - introduction
Laura Vass: Welcome to the interview with our working group jurors from the 2022 DevPortal Awards. We have here with us Sophie Rutard, Meenakshi Khatri, Bob Watson and Matthew Revell. I would like to introduce you first Sophie. You have been representing both a nominated portal before and you've also been a juror last year. You're working for years now as an API strategist for Allianz Trade. Some people might know it as Euler-Hermes the former name. And you were behind creating the first customer-facing API of the trade insurance industry and putting in place a support team and the developer portal that goes with it. You've also been significantly contributing to Euler-Hermes' Digital Transformation program, which resulted in a fully API- and cloud-centric IT strategy that is currently being rolled out as a multi-year initiative. Welcome! What are you busy now with at Allianz Trade?
Sophie Rutard: Well since this year I'm working as a program manager for Data Hub, which is sort of the platform that makes data available of good quality and accessible to make value out of it. So it has data streaming, it has a data warehouse that replaces a number of legacy data. And it also has the governance of data and the API governance too.
Laura Vass: How is your experience as a juror for the second time?
Sophie Rutard: Well, it's exciting. I enjoyed it very much last year already, and so I was very happy to be asked again to do it this year. And especially since I'm less operational on APIs than I basically would like to be. I see these candidates and it's just great to see all the evolution since just 12 months and all the great ideas. So it's really a lovely experience.
Laura Vass: I also would like to welcome Meenakshi Khatri. Meenakshi was representing the Giesecke+Devrient Convego Connect APIs developer portal last year as a nominee. You have been working as API product and business specialist across various FinTech companies for over 12+ years, where you bring a broad range of professional experience in launching APIs as a product and services, roll out API innovation transformation programs, and building API-related Phygital experience across various industries. And to top that, you've been working as a Java developer for more than six years. In your current role at Giesecke and Devrient, what do you do?
Meenakshi Khatri: Hi, Laura. Hello, everyone. So currently I am leading the developer portal team as well. And also the other products in Giesecke and Devrient. And my focus has always been to think out of the box, because how APIs can be perceived in classical technical companies is not the way we can replicate it. We work very much with hardware products such as payment cards. So even if we want to launch APIs, we have to strategically decide who would be our customers, who would use the APIs, is it a system or is it an end user? And how can we then roll it out to the right target audience? So that has been quite exciting. I started evangelizing developer portal and APIs in my company five years ago, and now we have a developer portal, which is serving all our customers across the world. What's exciting is our customers didn't think that a company like Giesecke and Devrient would offer APIs, and we broke that stereotype and we offer APIs to manage all the payment industry related data. So that's what I do in my current role.
Laura Vass: Thank you. And welcome.
Meenakshi Khatri: Thank you.
Laura Vass: Matthew Revell, known to many as DevRel supreme, and behind the DevRelCon global conference series, you're also known to many as the founder of Hoopy, where you provide DevRel strategy consulting and developer targeted content to help clients across the world understand, reach and work with software developers. And then some people may know that you're also behind developerrelations.com, which is the largest library in the world for developer relations content for which we thank you. Thank you for all your work in developer relations and welcome as a juror. How is the experience so far?
Matthew Revell: Well, it's been really interesting to see all of the real variety of developer portals that are out there. And what's really wonderful for me is seeing how different industries and different, I guess, target audiences are being brought into the world of API's, of developer portals and developer experience now.
Laura Vass: And let me introduce our fourth juror of the group, Bob Watson, who has been with the DevPortal Awards from the very beginning. You are currently senior technical writer at Google, where you bring industry experience and academic research together with the enthusiasm to prepare tomorrow's engineers and technical communicators for the diverse challenges they'll face as professionals. You also blog at Docs by Design, where you ponder over technical writing, API documentation, and the world in general. Thank you for being a juror again you're the pillar of this award. And we had many conversations about how, whether this is a competition or a celebration or what is this anyway... Welcome! And I would like to ask you first: in this year's nominee cohort, was there a nominee that specifically stood out for you?
Bob Watson: Yes. I'm a technical writer at Google, and I'm right now the lead technical writer for the angular web framework. And so technical writing is kind of what I key in on. And one of the websites that stood out in the competition whose writing just literally caused me to sit down and take notice was that of the Aiven's website. And like I said, like when I see crisp, clear writing and topics that are well organized and they're just a pleasure to read, I think that deserves to be called out and recognized as such. And so I wanna make sure that got noticed because all the entrants are interesting and amazing in different ways, but like I said, the one near and dear to my heart is the writing. And so I wanted to call that out.
Aspect of developer portals that coming more into focus
Laura Vass: In the overall picture what aspect of developer portals do you see coming more into focus? If you compare it with several years ago?
Bob Watson: What I saw most coming together and I think it's a good thing, that first I'm seeing kind of more standardized API references. That's always been a subject near and dear to my heart, as you know, when I was a developer and as a writer, because I think that's what's the most under-recognized aspect of documentation. It's great to get started, but at the end of the day, you need the references to actually get finished. So that's what I call the getting finished content. And it's good to see some of that standardized, so it's a little easier to follow. And I think standardizing, having clear reference topics mean to me that there was a thought given to the whole API experience, not just the feature. And so that's like the feature, how's it gonna be used, how's it gonna be integrated with other things? I think when you see good API documentation that you generally will find a clear API underneath it. And so that's something I think we're seeing more of, but I'd like to see a lot more of that just because that makes a whole developer experience a lot smoother.
Laura Vass: Meenakshi, what do you think about this? Did you see, when you started building the portal, were different things more important than today?
Meenakshi Khatri: Yes and no. So when we started building the devportal for us we had to first find out the business case. What kind of use cases we actually wanted to present because we are at a stage where we can just expand all our aps and make it available to everyone, or we create use cases, which would actually have some meaning and useful purpose for our customers. But on the other side, I also agree with Bob because it's not just rolling out an API, using some swagger tool and 'there you have the API documents,' but if you have a clear description, if you have the clear explanation of how to use it, and if it is fully self-service, that is what adds value. And this is what I have also seen the trend in the recent years that when APIs were created in the past five years compared to now, many companies decided, 'Let's just create a swagger file and make it publicly available.' But that is not it. You need to explain the prerequisites needed to even go through the document as well as the post-requirements, which is, once you have used API, next is 'Now what? Are we going to launch it? How are we going to put it in the production system?' And these, this is what one key thing that actually interests me with all the nominees, because many of them had some APIs which were not fulfilling as were the needs, but then the others actually put in the effort to show that you can just use the API connection out of the box without putting much efforts. So that's something quite new, in the recent years especially.
Laura Vass: How do you see this, Sophie?
Sophie Rutard: It's a bit similar. I really like the way that people go in a very complete documentation. And of course it starts with the swagger, and this is now sort of... You don't need to discuss it anymore. That's great. And then when I see how people add videos and how they add use cases, concrete real use cases that give you a direction on what can you do with that API in your own business process, I see there's a lot of investment done into this, people really putting time on it. Also providing the right visuals that help facilitate the understanding of it, that's really great. And I know it's a lot of effort to produce that, and people are ready to do that because they see the value in making the users of their portals as autonomous as possible. That's really great to see.
Laura Vass: Do you see this similarly, Matthew? And are there specific approaches that really stood out for you?
Matthew Revell: I think there are two things that I've noticed. One is the productization of APIs. And so that means bringing the techniques of product management and product marketing to something that, as other people have said already, used to just be an open API spec thrown out there and hope for the best. Whereas now we're seeing a great deal more of the context placed around APIs as products. And one of the things that we've seen in the developer portals that have been nominated for the awards is the idea of use case driven product marketing documentation. So yeah, I think documentation sometimes can be marketing and vice versa. And what's really great about that is it helps you to take this raw API and get an idea of how you could actually make it work. And I think it's Mercedes-Benz that has a section on each of their API overview pages, which is something like, 'Why does this matter to me?' And I think that's really important. And the second thing I would say that I'm noticing is the blurring of the lines between traditional documentation and things that put the API into the hands of the developer without them having to make too much effort. So I think a really good example here is a Postman collection or something like that, but also you see, or I'm seeing, increasingly interactive documentation, which allows you to get hands-on in the browser without installing anything or really making any great effort. And I think that kind of thing is really important to helping developers overcome those initial steep learning curves that you can often have when grappling with all those new concepts in an unfamiliar product.
Interactivity and solutions that used to be a novelty
Laura Vass: When you say "interactivity"... this came up with all the jurors actually, they all mentioned this. So I want to ask, what level of interactivity do you think is sort of standard expectation now from business or software developer visitors who want to implement? What used to be maybe novelty is now surprising if it isn't there? Especially when it comes to interactivity.
Matthew Revell: I think that there is a gap between developer expectations and what is considered to be a standard for delivery on the vendor side, quite often. And when I've done observation studies with developers learning new APIs for the first time, one of the things that they really value is the ability within the reference documentation to actually try that endpoint there and then. So for some vendors, you'll have, you know, kind of a virtual terminal where you can paste pretend curl commands or something like that. In other cases, it might just be that you click something and it will give you the return that you could expect with the data you've provided. So I think that's kind of, I wouldn't say it's a standard expectation, but it's something that's increasingly appreciated by developers when they're learning. But I don't think all vendors are there yet, but I think that's kind of the basics that we are gonna see over the next 18 months. It would be weird not to have that level of interactivity, and there are people who are doing way more involved stuff, but I think that isn't an expectation.
Bob Watson: I just like to add to that the interactivity is I think becoming more and more of an expectation. But what I've seen is that in and of itself, it isn't sufficient. You still need the supporting documentation around it, whether it's in the reference, you need to show, what the parameters are, and then have the ability to try them. You can't just have the ability to try them without an explanation of the 'what they're doing.' Likewise, in tutorials, it's important to have the ability to, read and then try, but you can't just have code because just having code is where we were without documentation. So that was the read-the-code-documentation, and that's one way to do it, but that's where the technical writing can come and help explain what's going on. And then with the interactivity, you can try it. So I think that's the gold standard is to have both having good documentation is great, but you need to try it. Being able to try it is great, but you need to know what you're doing. And so having those side-by-side I think is a powerful combination.
Meenakshi Khatri: I also think–besides trying out the APIs the key thing which I still felt amongst all the nominees–was how quickly I can reach the API reference page. So if I know the company or if I know which domain they're trying to target their APIs as a developer, I would prefer to directly just jump to the API reference without having a sign-up process. This is also something which I think is not a nice-to-have a must-have feature, because the more restricted the APIs are the less they're getting exposed to the outside world.
Sophie Rutard: I'd like to add to that, the part of the communities, I see that forums, they kinda are nothing special anymore, they're pretty much everywhere, and that's good. And then what's really interesting is then those portals that go far beyond that, to really animate the users to give feedback, to give responses in a very transparent way so everybody can benefit of it. And I also see that some must have a really good back office in treating those feedbacks, and working on the content, and continuously investing in improving and adding content to make the portal a really living thing that's basically getting better every day. That's really good to see.
Things that would be better to stop being standardly done
Laura Vass: Can I ask the other way around? So this is the things that you're happy to see. What are the things that you wish would stop being standardly done, and it's time that we stop with that?
Bob Watson: So I have one for that. One of the things that I still see that I think we should, we should have been past this a long time ago, is how, when the marketing and business side of the documentation is apart from the developer side. I think it's important to recognize that the API audience is a technical one, and that the marketing interests are technical and that the technical interests still have an interest in the business. And so keeping those separate, I think, you know, while I understand all the reasons why that happens, I think that that's not necessarily a good sign for a customer to see that they're treating this separately. 'What's my experience gonna be once I sell it? Am I gonna be on my own? I wanna know that they're in this with me.' And you know, that we have a shared interest in success. And I think when you can merge those together, where the marketing and the technical sides, the value proposition side of the documentation is close to the explanation of how it works. I think that's the part I'd like to see more, because then to me as a customer that would say that we have a much shared interest in acquisition and application because I can see that that's how they've organized their site.
Matthew Revell: I'd echo that. I would say that I'm kind of really surprised at how often companies put a lot of effort into creating an API. And then the documentation, or if it exists, the developer portal is really just makes the assumption that the developer working with that tool has no choice but to work with it. And that the decision to use that API was perhaps made on a golf course somewhere between two people who never touch code. And I find that really disappointing because even if someone else is making the sales decision to bring that tool into a company, good documentation and a good developer experience generally makes people more effective. It lets you make better use of the tool. And even just from a real mercenary point of view, it increases the chances that the vendor will get a renewal at the end of the contract. So I'm kind of surprised to see companies still just throwing APIs over the fronts and hoping the developers will just work it out for themselves. So I don't think in 2022 we'd still see that, but we do, and that's one thing I'd like to see go away.
Sophie Rutard: I completely agree with what you're saying, and I think it's important to understand that developers are not just coming in and executing and then it's working. They are part of the company they work for, and they are an elementary part to that. And also for the decision to take one API or another, they are elemental because they will confirm to the decision-makers eventually that they see that this service looks good and it has the basics that they need to build a solid solution. And I think not taking that into account and, for example, doing all the documentation, and then when you want to start trying it out, then you have a like, 'contact sales' button and you're completely blocked. You cannot do nothing. You don't know what it will cost because the pricing is not clear. You don't know what you will get when you click that button and so on. I think this is not what you should do in 2022 and upcoming.
Meenakshi Khatri: The things I would like to see more and what I don't see and things that should go is I agree with Sophie that in the end you see a nice contact button and that's the end of the flow. What I still want, developer portals to also give us more recommendations of what other services they could use which very few of them do today. So I've seen this in Visa developer portal where I either can choose an API or I can choose a use case, and the use case shows me nicely which are the APIs you would need to package and use this as a use case. So developer portals at most companies are trying to achieve that but as Sophie said if I'm a developer, I'm using one and I know the other API would serve the need better than what I initially thought. That kind of recommendations should be more often seen. Why I say that is if the company invests so much in creating a quality content, then I'm pretty sure that they can also narrow down and find different APIs which are similar and they can categorize it better rather than just putting it out there and letting developers figure it out. So that is something I would like to see more. And also what I don't want to see more is a dead end, which Sophie said 'contact me' or 'get more technical support'. And then you don't know what happens once you go in production. What happens, how is the life of the API, is it still being used or what happens? Yeah.
Advise on the future of API user experiences
Laura Vass: And all of that evolution, of course, happens in context. And part of that context is resources. Part of that context is legislation locally or globally, culture, cultural acceptance of certain moves, let's put it that way. Or simply the available technology solutions out there. If these would not be there, these blockings of the context, and you could just kind of dream up how you would imagine a devportal in the future. What are the things you could imagine would be awesome?
Sophie Rutard: I have seen one portal that did sort of a pilot or a beta version of a low-code application. And that really made me dream because if we could get to the point where we can just drag-and-drop features into a low-code platform, but maybe not just one, but let's say one of the top 10 or more, that would be quite cool.
Meenakshi Khatri: I can think of IKEA as an example. When you buy IKEA furniture, it's what Laura, you said about your question. So I recently purchased something from IKEA. They give you a nice instruction, it has no words, it just uses pictures and it fits across all cultures. So they sell the same furniture across the world and they don't need to use any language to explain how to build their product. So the same way if developer portals could make it little more, I wouldn't say colorful, but more creative to explain that, 'oh, using this API, you could do this', without using words that would be completely out of the box.
Bob Watson: So I think that we've been sitting on the secret to the success for this for... going on 20 years now. And the success of the API all comes back to the design of the API and how an API is a user experience. And by designing APIs from a user experience perspective and making them easier to accomplish whatever task it is they do, that everything from that just becomes easier. The documentation becomes clear, the application becomes clearer, the use becomes easier. And I think that's the one thing that some APIs get better than others. But if it seems like it's interesting that I think your question was, 'What would the future be?' And I say that the future is just, learning from the past. I mean, these lessons were discovered decades ago, and yet they still haven't been applied for some reason. And I'm not sure why. When I've heard things like 'APIs aren't the UI.' Well, they are to the developer. A developer is using an API very, very intensely. And so not thinking of their use when you're developing the API is ignoring the audience. In a consumer product that would be unthinkable. Like, 'No, we have to get the, we have to do user/customer research, we have to do focus groups, we have to do all this.' But for an API, those conversations are rarely heard. You know, I've heard that error messages aren't user experiences. And I couldn't disagree more. Error messages are very critical user experiences. And so I think applying, taking the user experience methodologies back up the chain to the API design, when they're actually coming up with how it does what it does, I think that's the key, the secret to success that we've been sitting on all this time, but still seems to be undiscovered for some reason.
Matthew Revell: I almost feel as though perhaps even a majority of API projects in companies start out as though nobody has ever built one, or at least a public API. And so it was kind of cobbled together, what they think works, and they try reinvent the wheel each time. And, you know, the problem you get there is that they're not building on all of the experience that's gone before. And the other face of that is that it's relatively rare that people go out and do developer experience testing. So actually putting it in front of real developers and watching them struggle with it. I did a developer observation session for a really large brand names API platform last year. And it was remarkable watching them. I would say probably 70% of them couldn't get past the authentication stage within the first hour of the observation session. And you have to think, 'Surely someone already knew that within the company?' But the problem is that it lack of resources, lack of understanding of developers as human beings who are varied and have thoughts and feelings and needs as opposed to just being some kind of stop on a flow chart means that the same level of product building and research and empathy for the end user who is the developer in this case, doesn't seem to go into these products enough. And so I think that's why we see these mistakes being made over and over again because one, people are almost doing a clean room kind of implementation of APIs. So as if no one else has ever built one before. And secondly, nobody thinks to ask the developers, I'm not gonna say nobody, I mean, in those particular cases, there are some companies who are doing an amazing job here.
Bob Watson: I think this gets back to your comment earlier about applying product methodologies and product development. It's that component where if you were to compare an API to any other commercial product and show the process to the product developments who've developed other successful products, they would just stare in amazement. Like, 'How could you do that?' I just can't help but think that.
Matthew Revell: I think one of the problems that I see quite a lot is that developers–rightly–demand high salaries for their expertise. And so what happens is you find people who are not necessarily developers in charge of API projects and perhaps through no fault of their own, they don't, to use a very geeky word, they don't rock the processes and needs of developers. And so, you know, they might miss things that they don't even realize exist because they've never experienced it themselves. And that's why I would always go back to the research and the observation with real life developers because that helps you to uncover all those things you might never have thought about.
Laura Vass: Thank you for the crystal balling.
Closing Thoughts
Laura Vass: Very excited to whom you chose as a board winners. We'll see. Thank you for all of the effort and attention, a lot of goodwill I think that you have put into this. We are very, very grateful and honored to have your expertise and your focus on the nominees, and I hope that everybody's portals are going to become better because of the advice and the nudges that you are giving. So thank you in the name of everyone who has their eyes on this awards program.
Matthew Revell: Well thank you to you and Pronovix as well.
Sophie Rutard: Yeah, thank you for the organization that makes it easy to spend the hours without regretting.
Meenakshi Khatri: And special thank you to you and your organization because you'll have been putting so much efforts to bring out this community out. And I would also suggest everyone to keep reading your blog and articles so that they can keep improving their developer portal for next year's nominations.
Laura Vass: Thank you.
Bob Watson: It's always a pleasure and an inspiration. And after doing this for a few years now, it's encouraging to see the growth and the improvement over time. So I'm optimistic. And like I said, as someone who's in the business it's inspiring for me to see how everyone else is improving. So that gives me new ideas too. So I appreciate all their hard work and look forward to next year's entrance.
