Table of contents for the Transcript
General introduction [0:00-03:23], Jury Group - introduction [3:24-07:34], Particular qualities that struck the jury members [07:35-11:35], Features that used to be a novelty, and become standard expectation [11:36-14:42], What 'interactivity' means on a devportal? [14:43-17:27], Something that shouldn’t become standard [17:28-19:55], Processes or solutions that would be great to see more often [19:56-21:49], Cognitive accessibility [21:50-28:23], Closing thoughts [28:24-30:15], General closure [30:16-30:40]
Back to the DevPortal Awards 2022 Jury Interview page »
Transcript
Jury Group - introduction
Laura Vass: Welcome, this is the DevPortal Awards 2022. This is the first interview with our jurors this year. We have 11 jurors, and I'm interviewing first three of our jurors: Anne Gentle, Anthony Roux and Alvaro Navarro. Welcome!
Alvaro Navarro: Thank you!
Anthony Roux: Thank you for having us.
Anne Gentle: Thank you.
Laura Vass: So first, short introductions. Anne is an industry recognized author. Your books promote collaboration among developers and writers, and you work as a developer experience manager at Cisco DevNet, the developer program for Cisco Platforms to connect, secure and automate. Thank you for being a juror and for being here today.
Anne Gentle: Absolutely. Thank you for the opportunity. So yeah, I work at Cisco and I manage developer advocates, API documentation, and we work across multiple engineering teams to produce developer.cisco.com, which is our developer portal. So I'm always looking at developer portals to see what's happening in the industry. I'm of course super interested in it for research for my book which is about using GitHub and those kind of like developer-based techniques for authoring as well. So it's very, very close to the code, very close to developers. So I'm always on the lookout. So being a juror is just an opportunity to keep reading, keep doing research. Absolutely. So, yeah, I'm happy to, happy to dive in.
Laura Vass: And your book is now at its third edition. Fourth?
Anne Gentle: Yes. I am waiting for the print proof, literally to show up at my house so I can approve it.
Laura Vass: Our second juror today is Anthony Roux. Anthony works as developer relations lead, at Miro,, and you're calling in from Amsterdam. How are you doing, and well, most people who are here probably know you, from prior API The Docs presentations. So what are you currently doing at Miro and how do you look at developer portals now?
Anthony Roux: As you said, I've been involved in the API industry and in general developer relations industry for about 10 years. I participated in various API The Docs events. I used to be on the other side of the work, with making our developer portal. We used to work with Alvaro, entering as well and got an award for that. And moving to the jury part has been super interesting. It's really looking at it from a different eye and realizing a lot of things that I was seeing as someone's making or building a developer portal is very different as looking in detail and looking at so many other developer portals. It's a very good learning opportunity. I'm not doing research as Anne, but we're training every day at Miro to improve our developer portal. And in general, the developer experience and being able to learn from so many very good developer portals has been really really good. And that's learning I can bring back to my teams, share with them, and we can improve what we have. So, so far we liked it as well, was a good opportunity to work and collaborate again with Alvaro and meet Anne. So, so far, very, very excited.
Laura Vass: And Alvaro Navarro currently works at Spotify for developers. And you're an open source lover and for over a decade you work developing and advocating technologies at companies such as Airbus and Amadeus. How is your experience so far as juror?
Alvaro Navarro: Has been great. Thank you for the opportunity for joining this amazing Developer Portal Awards. So I had the opportunity to work together with Anthony at Amadeus, working with APIs, the developer portal. So based on all this experience were helping a lot to assess all the nominees of the developer portals. And also right now that we are working continuously improving our developer portal at Spotify it's a great opportunity to bring all this knowledge back to the company and also to the awards. So yeah. Thank you for the opportunity.
Laura Vass: We are honored and thank you for joining.
Particular qualities that struck the jury members
Laura Vass: What are the approaches, and I ask first Alvaro, what are the approaches that you really liked from the nominees? What are the particular qualities that struck you?
Alvaro Navarro: Yeah, I really like the ways some developer portals have implemented, for example, interactive examples to help developers understand their product. But also, I would like to mention one developer portal that implemented something that, I'm not used to seeing very often, is an anonymous sandbox which allows developers to make API calls without creating an account, that is amazing. And as I said, it is something that we are not used to seeing and this is a really, really great idea.
Anthony Roux: Yeah, maybe I can add on that. Very, very similar feedback than Alvaro. The first thing that I was really pleased, and I really like, is I see many developer portals trying to make the onboarding process as simple and as quick as possible. There is one developer portal that has been amazing in doing that, it's the PlatformOS one, they had a one-click setup. You can literally set up all your environment and start playing with it in a second. And that was fantastic. I really liked as well the part of being able to start testing, the one you mentioned Alvaro, the anonymous sandbox where you literally go to the developer portal, you access the interactive documentation and you're able to test it right away. There's literally no barrier to test. And that was very, very good. If I remember well, that was Fiserv. Another thing I would like to highlight as well is–and I think that's improvement that I've seen over the last years–is that there are more and more visual testing, they are offering more visual way of testing instead of just... There's this thing where we have been accessing a lot of text-based style developer portal, we spent our life reading Json. It's really refreshing to see companies that are bringing a new layer to that. And the one you name Alvaro, in which you have a demo application, visual demo application you can play with that is linked to the documentation next to it, I found that brilliant. And that's improved a lot the developer experience. So yeah, big kudos to Chase, I believe, on that.
Anne Gentle: Yeah, and that's the one that really, really struck me was that people were working really hard on use cases, which I know are hard to come up with. You have to really think about interactions, think about what the users really want to do, and then code it. And I think the Chase one absolutely stuck out to me, it's interactive in the browser. It's very step-by-step still and you know, explaining to anyone who, even if you're new to FinTech or you kind of have to think through, 'Well, what is my app really doing?' It just was a great visual and very, you know, self explanatory. I really, really appreciated that one.
Anthony Roux: And if you think about it, it's very inclusive as well, right? It means where before you needed to have some more technical background or being able to browse into these APIs, having a visual layout on that, it invites many other different persona, where people have different backgrounds.
Alvaro Navarro: Yeah, that's true.
Anne Gentle: The other one that I think Alvaro, you might have kind of like, the idea that struck me as well is the idea that not all of us wanna trade our data for information necessarily. So I think we're all getting more aware of that. And so there was that site that was like, 'You know, cookies are just for eating on this site.' Like all three of us were like, 'Wow, this is great!' And I think that was another sort of central theme that, you know, we felt like, 'Oh, you know what, just, you know, to be a developer, you don't have to feel like there's this transactional, here's my information for some information.' So that one was just, all three of us just was... It was a jaw-dropping moment.
Features that used to be a novelty, and become standard expectation
Laura Vass: What would be the one feature–beyond 'Cookies are for eating,'–to name that used to be a novelty, like the ones that you just mentioned, years prior, and you are really glad to see that it's becoming kind of the standard expectations from a developer portal?
Anthony Roux: I think I have two that comes in my mind. First one is the one we mentioned before, interactive documentation. Interactive reference documentation became now the standard when if you look at a couple of years back, it was not. And that for me, that was one of the biggest improvements in developer experience. Not having to set up a developer environment just to discover or test quickly something, that's been a very, very good improvement. And what comes with that as well, there are so many API products that work in very complex industries. I can think about finance, for example. And they've been able to bring sandbox environments that replicate the finance industry to be able to test these APIs. Where in the past it was almost like, 'Well, if you're not part of that industry, you cannot really test anything. You cannot really discover that.' All these sandboxing, which is free and accessible to everybody in a simple way for these APIs, for me, has been a big revolution as well, that I'm very happy to see. And I think that now sandboxing became part of a standard requirement when you build API products, which was not a couple of years back.
Anne Gentle: I think that's very true. And I think infrastructure accessibility is super important. One of our catchphrases is 'Not that everybody has a million dollars worth of Cisco gear laying around'. And so it is part of that accessibility everywhere. And I think one that really stood out to me is the Mercedes-Benz site with a sandbox and you can bring your own car... That was amazing! I'm like, 'Okay, time to go get a Mercedes.' Cause that's a great developer experience. So I do think just, you know, sandboxing, accessible infrastructure, just making gear available is just what everyone needs. Software developers, infrastructure engineers, if you're in DevOps, it actually encompasses a broad array of technologists.
Alvaro Navarro: Yeah. I fully agree. I think one of the most interesting things are the interactivity with the developer portal. To me the biggest, the most interesting one is the examples, but also the API reference, that in the past used to be something static. And now having the typical API reference where you can make API calls, modify the parameters, et cetera, is like kind of standard for every developer portal. I think that's super important. One of the things I really love that is again a new standard these days is multiple programming languages when, reading examples, not focus only on the two-three typical programming languages like, 'Okay, so this is enough for everyone.' So now it's like we try to cover all the different profiles, personas, from the developer community and that's super, super important.
What 'interactivity' means on a devportal?
Laura Vass: When you say interactive and that you are really happy to see more interactivity on portals, when you say "interactive", where does that start? What is interactive?
Anne Gentle: I think that's a fair query in line of questioning because you want as a developer to be able to try things out, but product to product that could vary widely, and where the user starts from, their own knowledge. So, you know, we use the term ‘hands-on’ a lot at Cisco, but if they don't have a basic knowledge of even Linux, that might be a barrier, right? So for us, interactive is, even as far as like a terminal browser, a terminal window inside the browser, all the way up to access to, you know, infrastructure behind the scenes. But I think the standard that everyone expects is "Try it out." That button has become interactive, which means I click a button in a web browser and I get a response. I'd love to hear y'all thoughts though, too.
Alvaro Navarro: I am pretty aligned with that definition of interactive. For us it's kind of the same. So, interactivity is, when you use a developer portal, for example to perform an API call, you get that response and that response helps you to really understand the schema, for example, of the API. Or you have–as we have seen in many developer portals from the nominees–you have a small example that you can tweak, you can modify a little bit, and that invokes a call in the backend and that's modifying the front somehow, right? So you can really understand how this API is modifying the behavior of the client. That's, to me, the level of interactivity that really helps when understanding a product.
Anthony Roux: I would define it's about the developer portal, interactivity is everything I can do without having to set up an environment, but just playing and clicking around. That will be my expectation for developer portal interactivity. As soon as I need to set up a developer environment and learn some programming languages, run framework and so on, then have to do a lot of things on my side, then I'm not on the developer portal, I'm out. If you embed something on the developer portal, the "Try out" is a good example, but you could have as well as a JavaScript that you embedded and I just have to click around and that works. Demo app, which is embedded, I'll say consider it interactive because I can click around and play.
Something that shouldn’t become standard
Laura Vass: Is there a flip side to this? Something that's becoming standard and you wish it didn't?
Anne Gentle: That's a tough one. There's a lot of Swagger UI that's not really stylized. So to stand out. The ones that sort of look like Swagger UI, but they had, you know, definitely stuck to something that was their brand, maybe added some little bit of flare that made you know 'I'm on the TomTom site.' I think one of their pointers turned into a geo-pointer, right? So anything you could do to just make your reference docs not the thing you see everywhere, that would help.
Laura Vass: Any pet peeves, Alvaro, Anthony?
Alvaro Navarro: I was actually thinking about Swagger as well, because, I mean, implementing and integrating an API references is not easy. Many developers portals choose to integrate Swagger UI, which works fine, brings many functionalities out of the box. But if you don't tweak a little bit the UI part, the integration with the rest of the portal, I mean from this whole perspective doesn't look good. And yeah, that's something that I've seen there many, many times.
Anthony Roux: I have one, it may be a little controversial. OpenAPI specification brought a lot of very good things, and automation, which means now almost all developer portals have client libraries, which is fantastic. And they have many languages. The part, the difference I've seen is many companies decide now to use only the autogenerated version of the client libraries and many of them decide to not invest as much in building the high quality handcrafted SDK because now you can scale in many programming languages with automation, which is fantastic. But I felt that when you tried some of them, you feel on the developer experience, that is still a generated code. It doesn't offer such a fantastic developer experience. So I'm very happy to see more of these, I'm very happy to see automation. I just hope we're gonna find as an industry the right balance between automation and as well offering good high quality developer experience for the users.
Anne Gentle: I agree. That's investment and that's really having empathy for the developer.
Processes or solutions that would be great to see more often
Laura Vass: Are there processes or solutions that you wish we could see more of, even though maybe we can, we can acknowledge that the times are not yet ready for it. So when it's not necessarily a question of money, maybe a question of culture, maybe a question of legislation, or the missing technical piece that's just not there yet. We can imagine, you can imagine, but it cannot be, for some reason it cannot manifest yet. Do you have an idea for things like that?
Alvaro Navarro: I would love to see more developer portals paying more attention to accessibility. That's, to me, one of the things that I really miss in many developer portals. Is the time already here? I'm sure it is. So probably it's a matter of, you know, resources, time. But yeah, I think it's important to make developer portals inclusive for everyone.
Anne Gentle: That's the one that sticks out to me as well. And I think it goes hand-in-hand with inclusive language, that is accessibility for all. And it's inclusive language for abilities, for humans or humans for, you know, race, for gender, gender is not binary. And I just think that the teams that applied in the Accessibility [awards category], nearly all of applications also mention inclusive language. So I know these are in our circles definitely being thought of hand-in-hand, which is what we wanna keep striving for. Because I do believe that is the encompassing sense as this is about, you know, bringing more people to your site and letting them work on it. Work on the tech there.
Cognitive accessibility
Laura Vass: For me, when you're talking about the inclusive experience and the accessibility, I'm very keen on cognitive accessibility, both in the official meaning of cognitive accessibility, but also in the everyday meaning as in 'This is a wall of text, and please give me a drawing.' These seem to be conflicting with each other, but we still do see a lot of text on these pages where not everybody is necessarily thinking in words. What is your opinion on this?
Anthony Roux: I fully agree. I would love to see more visual representations of concepts, in general. More diagrams, more graphics that will help people to visually understand things without having to read pages of text. If we look at the current proposals we have, most of them are heavily text-based. It means you have to go through pages of pages of explanation to understand concepts. They have very few images, very few diagrams, and if it's the case, everything is still very static. Most of them are screenshots. They are not customized for the onboarding. They are not customized for what I'm looking for. I would expect to be able, similar to when I experience an API reference, to be able to see visual representation of the data. Not always have to read Json, but as well, when I read about use cases or what the product does, to have visual representation, diagrams, graphics, images, that help me to quickly be able to understand what it is and convince me to spend more time reading these pages. And there are still very few of them, it's still an industry where we're heavily text based.
Anne Gentle: You know, I was looking back through our sheets even last night to jog my memory on the visual design. And the visual design is still very beautiful on the starter pages and the sort of orientation to a developer portal, but then you go to the documentation, it's like visual design just falls by the wayside that we even had to struggle on a lot of pages to find a graphic to judge it. I feel. Even going back through notes yesterday, I thought, oh wow, the visual design, there was a lot of it on the portal. Then you get into the docs and you kind of, it's a wasteland even, unfortunately. So it's a good point.
Alvaro Navarro: I'm okay with the idea of having more diagrams and images in the documentation. As long as these images have a well defined purpose and help developers to understand something in particular, I think it's fine. It's not for the sake of having more colors and, you know, images in the documentation. So yeah, and I agree. I mean, we are used to seeing documentation based on text because I think is what developers are used to consume, let's say. But probably we can think about that as an approach of providing more content that helps developers to understand what's going on.
Anthony Roux: I do agree a hundred percent with what Anne and Navarro said. Maybe I can add to that, [I would like to see] a better or more localization. I think it's still a standard expectation that everybody speaks a decent level of English to be able to use technical products. When you think about it, what's the percentage of the world of people that are really fluent or very good in English? Many people might understand high-level what it means, but if they were to dig into the product, that's a big barrier. And language is one of the biggest barrier to collaborations and must probably be one of the biggest barriers to being inclusive in the product. So more and better localization would be fantastic to see. I don't know if we're ready for that because we understand that technically it's difficult. But I will see, it will be a very good step forward for the industry.
And another one that I could think of is maybe a little bit more technical and linked to what we talked about before, there's still this very often this process when there's the need of creating an account and providing some data, like an email, validating the email. And there are a lot of steps that are still there before even discovering what the product is. And that's a big barrier when you think about it. Not everybody has time to invest to just discover if something is good or not. And by asking all these steps before just letting them discover and test it, you are potentially losing future developers that would have been interested in buying your product. And it's something that was the case long time ago. I see it getting better and we saw a very good example of the anonymous sandbox, but it's still not an industry standard. And it's still, for some complex industry reasons you still need to request access and you have some validation processes. I would love to see in the future more standardized processes or tooling that you can just try out of the box without zero barrier for adoption and then you can decide to create an account. And then if you want to invest and you're ready to invest in the product, that's the right moment to provide some of your personal data, like an email. But before that, I'm always like, 'Huh, do I really want to create an account, validate the email, to create a developer app, get an API key, just to see what it does?' That's still there. It was there 10 years ago and it's still there. And I hope in the future, these barriers can slowly disappear.
One that disappeared, at least I've not seen in a long time, which a couple of years back was almost normal, is to test a free product, you had to give your credit card. And that was driving me mad, insane. I have not done that lately, so at least things are moving forward, that had gotten better. 'Test it for free, but give us your credit card information. Like what?!'
Anne Gentle: Yeah, like the credit card, should that be your identifier? And not everyone has one, yet. So cutting off a lot of students, that's not the right, you know, that's not the barrier to entry you want either. So I think the industry has moved forward from the idea that a credit card is your ID.
Anthony Roux: There are countries, big countries, that it's not easy to get access to a credit card or you cannot, so that's, you literally remove them from the potential users of your product.
Laura Vass: So that would be kind of a Wow experience if the onboarding would be more seamless, no demanding data and, and inclusive.
Closing thoughts
Laura Vass: Thank you very much for this interview, and also for your participation as jurors. Well we know, but probably from the outside it's not apparent, how many hours and hours and weekend hours and evening hours went into this, and how deeply you had to inspect some portals, especially where the chase was really close because they're all awesome and then it's hard to choose who's the winner this year...
Anne Gentle: I wanna take a moment to recognize how much work you all put into this year over year. I've been a juror over the years and seen how much work you've put into the assessment sheets, how much smoother the process has gotten year over year. You all are doing a great service to the entire devportal industry. So I want to take a moment to recognize that as well. This helps all of us so much and to see how much you all grew this over the years is just wonderful. So thank you.
Alvaro Navarro: Yes, thank you.
Anne Gentle: And your whole team. Thank you.
Laura Vass: I feel very honored that we can enable this. I think we are enablers, this would not be possible without the work of the jurors.
Anthony Roux: Yeah. Thank you very much. Your team, you make the processes well feel very, it's seamless, but as well you feel about being of a group, belonging to a group, and speaking in something that is giving back as well to the community. So offering us a chance to give back after so many years, that I appreciate a lot, but as well, I really enjoyed the sessions, the way of communications, you handle all the processes and so on. I find refreshing, energizing, working on that.
Alvaro Navarro: And also thank you for your patience with us. You know, we to coordinate three different calendars, three, two different time zones. It is not easy at all. So yeah, thank you for that.
