Made by 
Made by
February 7, 2018
Events and Marketing Coordinator at Hoopy
Kristof Van Tomme
By its nature, dev rel work tends to put its focus on external things like customer acquisition and retention. However, in this DevRelCon London 2017 talk, CEO and co-founder of Pronovix Kristof Van Tomme makes a strong case for venturing over the firewall to ensure the developers working with your APIs aren’t succumbing to the “Five White Walkers of Motivation Death”.
I wanna talk about developer experience behind a firewall, because I think this is…it’s maybe not the sexiest subject, but I think it’s super, super important because I think it has ramifications all over the organisation. And I think it’s something that we need to become more conscious about and we need more talks about it. And maybe there’s even a separate event that’s needed for these kind of things because I think there’s a bunch of people that are having problems and that can’t really find a community to talk about it.
But before I really get started, I wanna say thank you, because when I’m here standing in front of you, it’s very easy to think like, “Oh, there is this guy and he knows everything and, you know, he must have lots of…” whatever. There’s a ton of people that are standing next to me and that are making this possible. Part of them…there’s obviously my family who is a continued source of inspiration, sometimes frustration, but…you know, small kids. But there’s a lot more people, because when I’m doing these talks it’s only possible because I have a team that is enabling me to do it, that are providing the funds for doing it by, you know, doing the work that they’re doing. There’s a whole community of people, there’s the people that organise this events, sponsors, there’s you and yeah, it just goes on and on. There’s too many people to say thank you to. I’ll mention a few by name, but I wanted to bring that up upfront first.
So, that said, we’re Pronovix, we are a consultancy that specialises in developer portals. We used to be a Drupal agency. We’re still doing Drupals but now specifically for developer portals. We specialise on portals that have like role-based access control needs because most tooling that’s available in the open source world is focused on like flat access. They’re all tools like, you know, generate something and put it out there. And if you have like multiple audiences it gets kind of tricky. And because of that we’ve been encountering like a different group of people and that’s what this talk is about. I talk in these communities. So what I’ve tried to do is bring together knowledge from a bit all over the place, from boat tooling, dev rel, API communities and the technical writer communities and to combine all the knowledge that is necessary to do a development portal because a lot of this is not really generally known or available and it’s very fragmented.
One of the things I do, if you’re from London, is the Write The Docs meetup here in London. You’re very welcome there, it’s a very cool community where you can learn a lot. And this is something that we’re working on, this open source product for building the developer portals. But why I’m doing this talk is because in the past 2-3 years we’ve been working on just over 30 portals. And there was this really weird thing that I realised, was that some of the biggest portals we were doing were for internal APIs, and this is weird. Or for me at least it’s kind of like, “This is funny,” because most of the talks that you hear in the communities are all about external-facing portals. It’s all about marketing and getting new developers from outside of your organisation to start using your APIs.
So to kind of explain why this is important, at least for part of the organisations, I think it’s important to take a little step back and to look at why organisations make APIs. This is one of those slides that I stole, or that I borrowed, from Manfred from 3Scale, that’s now part of Red Hat. And he did the strategy workshop where he talked about the different reasons why people do APIs. He mentions selling APIs, which is the obvious one that everybody starts thinking about, like making an API product. A lot of organisations start doing APIs because they have a mobile app and they need something to feed its information. And then data transactions is also pretty big. If you have boundaries that you want to cross with partners or inside of your organisation. Complementing products was not on his slide, but I added it because I’ve seen people like where I say, you know, “Sell APIs,” and they say, “No, no, no, we don’t wanna sell this. We wanna give it away, but it complements our existing product and it’s gonna make it better, and because of that we’re gonna sell more of our existing product.”
But I think the fifth one is the one that I really wanna talk about, and that’s internal agility because this is one of the biggest ones I’ve seen mentioned when people are talking about internal development portals. They wanna do the Amazon thing. They want to make their business into a microservice hub that they can like recombine and do all kinds of new innovative things with. And they just wanna speed up their organisations and to increase their internal metabolism. And this internal agility is really important, especially in large multinationals and organisations that have grown from mergers like if you’ve got telecom from this country combined with telecom from this country, they have their own tooling and it’s pretty hard to make it all fit together, and that’s when internal agility becomes really important.
This slide I got from Chet Kapoor from Apigee and I wanted to put this in because it shows…I really like the concentric circle model of looking at ecosystems that you can serve with APIs. Interestingly, different organisations start from different places. So they’re not always starting internally. They’ll often just jump straight into customer APIs or partner APIs, but some organisations really build like a foundation first and start with internal APIs and then use that as a platform that they can then build further for partners and for customers and maybe even for building an industry API ecosystem.
The secret life of corporate APIs
And so that brings us kind of like to this secret life of corporate APIs because as I said, it’s kind of weird, like why don’t we hear more about that? So let’s think a little bit about why is that happening. I think there’s three important reasons. One and two is budgets and permission. Companies don’t really like putting out their dirty socks and showing like, you know, all the things that are going wrong and how much they need to improve. There’s very few companies, especially at scale, that are happy to share that kind of knowledge especially if they’re on stock exchange, they don’t want that kind of information to be put out there. It’s kind of negative marketing, right? So it’s often hard for them to get permission.
The other thing…and sorry Phil, you’re not here, but I was looking for somebody who really kind of shows this image of the very busy, very successful dev rel person who’s all over the place promoting their platform by being generous, and I think Phil does a really good job at that. And it’s not a critic, because this is awesome being generous and sharing what you know. But because of the nature of the kind of APIs that developer evangelists are promoting, we have this skewed thing in our ecosystem where most of the talks are about public APIs and about the tooling for building public APIs are about teams that have massive budgets that iterate and iterate and iterate to make their APIs better because they have to because else they’re not gonna sell their product, but internally that’s a different story.
Now, what are the key problems that we’ve seen or that I’ve heard from teams? I found five problems. I call them the Five White Walkers of Motivation Death for this talk because each in their own right are really strong demotivation powers. First one is poor discoverability. This is one of the most common things that I’ve heard from organisations. They have hundreds of APIs all over the place and everybody’s just doing their own thing and they don’t have a central place where they have all their APIs and it is just really hard. Often the metadata about them are different so it just becomes really hard to find what you’re looking for. And this creates a lot of friction, because then you have to go and reach out to the leader of a certain division like, “Hey, we’re trying to integrate with you but we can’t really find a way to do this.” “Oh yeah, we have an API for this,” but maybe that’s like one or two weeks later and it’s a lot of frustration. One of the things that I think you can do for this is create a central repository of all your APIs with sufficient metadata. For example, functional domain space, data domain space, kind of like separating out like what APIs you have and make it easier to find things.
Second one is domain language. All of these four are platforms but if you’re building software, none of them are the platform you’re looking for. And often especially when you have different business units that have merged in the past, they’ll have their own way of talking about things. And to make sure that everybody understands the same thing is kind of difficult. I was brought to this by Zdenek who runs Good API, which is an API design company, and he… It was really fascinating. He said that before you start building APIs, like before you even start working on the design for the APIs…he’s doing now exercises for domain language, like just trying to figure out what is domain language, what do people understand under these words and kind of trying to harmonise the domain language across the organisation, which I thought was really, really fascinating. This kind of triggered some of my previous interests into Semantic Web and that kind of stuff. So I thought it was kind of cool and really exciting to see that, you know, to make a good API design, you might need to go back a little bit and to look at the words that people are using. Jenny Wagner earlier today also mentioned taxonomy as like a really important thing and I think this is very similar that’s, you know, making sure that people really understand what you’re talking about.
The third one is lack of design standards. And this is kind of an obvious one, right? This is something you still hear quite a lot about in developer evangelist community and in API space, is that you need to do proper design and make a good design for your API. It’s related to the previous point but still it’s distinct because it’s often also about structure. If you have in the same organisations different APIs using different structures, you’re gonna create confusion and frustration. At Nordic APIs, there was talk by…I don’t remember her name, from Microsoft, I should have looked it up. But she mentions that they had this massive problem with like I think five solutions for their identity management. So if you wanna get a user object, there were five different ways that you could get that depending on what part of the organisation you needed it for. So depending if you’re looking for this product, it was different than for the other product, it’s a mess. So and they started to harmonise that and…for next time I do this talk I’ll look it up. But her team worked on a graph database to harmonise that. It was really interesting.
Arnaud API Handyman is…he’s been doing talks in the API community about API design standards. He also has a free eBook about this. He’s probably somebody you should check out if you wanna learn more about API design. He talks about setting up style guides that then can be used throughout the organisation to structure your design. You could also use that to do automated reviews. There’s tools for that. He mentions two in his talk, but look it up. He had it recorded, or I helped record it in Berlin. And he mentions two tools that allow you to automatically check if the API design adheres to your style guide. It’s really interesting.
Fourth is the lack of documentation. Several organisations that I’ve talked with actually, and this is almost criminal, but when somebody tries to do an integration of a new API, they basically have a team that is gonna train them. They do workshops to train people to use APIs. And if you think about that one of the most important functions of developer portal and of APIs overall, is to increase velocity and to become a sort of self-service hub where you can just go, get the information you need to start to build integration. Now, this is kind of weird, right? Why would you want to do that? Why would you limit yourself to workshops to train people how to use an API? I’ve heard in the technical writer community, there’s different ideas about this. Like one thing, one really low-cost solution you could do is to have the person who’s being taught writes the manual about API and to use the process maybe even with new developers that are coming into your organisation to have them build a documentation for the API so that the next time, you don’t need to do the workshop. I’ve heard organisations where this is kind of like, “Okay, I’ll train you, but you have to write the docs,” kind of thing. So obviously, if you have technical writers, that’s even better. But behind the firewall there’s not always the budget for that.
And the last one, the fifth problem I’ve heard of that people mention is authentication. Like just fragmented authentication, different business units having their own authentication platforms that are not necessarily connected. So if you want to use an API from another business unit, you have to first get their approval or get an account. It’s kind of messy. So you probably wanna federate that or centralise authentication. And then, you know, you can afford the White Walkers of Motivation Death and make sure, you know, you don’t ruin your developers’ lives.
Now, can dev rel fix this? And I think…you know, could you do dev rel behind the firewall? I think probably you could. If you look at Phil’s Devrelometer, most of these things you can do behind your firewall and you just do for an internal audience, you know, provided you have a big enough organisation. And there’s actually some organisations that are doing this kind of stuff. Alison Gibbons at API Days in Berlin mentions how at RBC they’re doing some of these things. It’s not purely internally-facing, but to some extent they’re also doing it for their internal audience to make people more enthusiastic about API program to help with recruitment and so on and so on. But they do it with spillover effects towards the wider community which was, I thought, really cool. But yeah, as I said earlier, it’s hard to get budget for these efforts. Nobody has a money tree, yeah, it’s tricky and like it’s hard to prove the ROI of developer evangelism. It’s even harder to prove the ROI of internal developer evangelism. So probably that’s not gonna be that easy.
So I think…and this is me thinking about it and like going into discussions with customers because we haven’t actually done this yet. We have a few projects that are on their way but I think that’s…the key is gonna be in building better processes and some tooling. And I don’t wanna put full focus on tooling because I don’t think any problem is ever solved purely by tooling. I think it’s always a combination of improving the processes and tuning them to the tooling that you’re building. But I think that to do developer experience really well inside a firewall, I think it’s gonna be a lot about efficiency and making processes that are gonna give you a good developer experience, kind of like a default out of the box, you know, as part of the process. I think that…to do that, I think the core focus should be on developer experience, like on reducing the API friction throughout the process.
And here I’ve got…yeah, to streamline the API journey. And this is a journey you probably already know. It’s what everybody is talking about. Probably you have maybe different steps here or there, but the downstream journey, the downstream developer journey where you get an API and you integrate it with it to build an API integration, that’s kind of like what everybody is kind of familiar with. But I think there’s a hidden second journey and it’s the upstream developer journey. It’s the journey of people that are building APIs and that need to go from like, you know, “Yeah, we need to do APIs,” to, “What are the resources we should have APIs for?,” all the way through the design process, implementation to feedback and support. And I think that to make a great developer experience, if you can improve the upstream journey…so if you can build a good style guide, you can automate the check-in, if you can make good documentation about how you’re supposed to do APIs in a certain organisation, if you can help with standardising this and providing a good governance model, then I think that you’ll be able to improve the downstream experience, because maybe for example you could say your API is only gonna get five stars if you also have documentation. And you can kind of gamify the process and make it nicer for people to do what they’re supposed to be doing.
Is this really new? Probably not, standard operating procedures, business process modelling, these are things that organisations are already doing for a long time. But I haven’t seen people really talking about it in terms of API design and building of APIs. And it feels a little bit like the Wild West with the API space because it’s like new and everything is different but actually it’s not to some extent. And I think…yeah. But I found this picture…and unfortunately it’s in French, I only found it in French. But I thought it really captured the idea really well of what is different today in comparison with previously. There is this combination of lean business process modelling, new technologies, this notion that you really have to motivate people and not just tell them what they’re supposed to do. And I think this is creating a new environment where we might need to revisit how we’re doing things. In kind of this agile decentralised world, that you can’t just tell people what they’re supposed to do, you have to entice them. You need to make the writing also the most fun thing to do, I believe. And I think gamification can be really useful for that.
If you can give meaning to what people are doing in their work, it’s gonna be much easier to get them to do the things they’re supposed to do or that you would like them to do. If you make it the most fulfilling thing to make documentation and give them feedback and you, you know, use some of these gamification elements to…maybe even some of the black hat elements like the status notifications and things like that when somebody uses your API or builds an integration, you get an email like, “Hey! Look at that! Somebody else today started an integration project.” These might be things that can help drive the engagement in the organisation especially if you have like a really large one. But this feels a little bit like…this is really developer evangelism still then. I’m not even sure, it feels to me a little bit like it starts to become more developer engagement. And yeah, it’s more about motivation and the softer things that are…like it’s not really marketing anymore. It’s kind of internal marketing, but yeah, it feels more like engagements than marketing. But I think that if you want to do API programs at scale, if you want to have loads and loads and loads of APIs, I think that you need to do some of these things, because else it’s just not gonna work, or it’s gonna be too expensive and you’re gonna end up with a mess.
I heard a story of one bank, and they had like a really large bank with lots of divisions all over the world. And they had the problem of different APIs using different domain language, they were differently built, they had no discoverability, all these problems that I mentioned they were having. It’s kind of a waste to come to that conclusion after you’ve been building these APIs. It would be much better if you could start out and have a better process from the get-go. And one last point around that is that I think having a better process will also benefit the other ecosystems, not just the internal system because, as I said earlier, some organisations start with internal APIs and then use those to build up their API products and their partnership and so on and so on. And if you have those processes to make a consistent design from the get-go, it’s gonna help with, you know, the further steps later on also.
Summary, I think we need more talks from behind the firewall. So if you have any friends that are stuck in a large corp that might still get permission to talk about what they’re doing and how they’re doing their developer portals, you know, ask them to speak, get them to come to this event or to API The Docs or events that we run or something else, just get more word out because I think there’s…you know, it’s easier to carry a burden when it’s shared and it’s easier if we can learn from each other and help each other. There’s these five points that can really kill the experience inside the firewall and they’re somewhat related to the external experience, but they’re still kind of different because they’re…yeah, it’s slightly different than we talked about. I think that…I wanna reiterate that it’s important to remove friction also from the upstream developer journey, so not only from the downstream developer journey. And yeah, I think that if we can build better tooling and processes, that we’re gonna get better developer experience as a default from the get-go before you need to, you know, start retooling and reiterating because iterating is very expensive. Iteration is a very good way of doing things, but it’s not always feasible in, you know, no matter where. And if we do all of those things I think we’re gonna have a lot less harder days and that’s gonna definitely make our colleagues much happier.
That’s it. Thank you very much.