Document 360: #1 Knowledge Base Software
Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,500+ subscribers. (See email archive here.)

Search results

Document 360: #1 Knowledge Base Software

Developer portal strategies for complex landscapes -- conversation with Kristof van Tomme

by Tom Johnson on Jun 24, 2020 •
categories: api-docpodcastsstitcher

Recently I chatted with Kristof van Tomme, CEO and co-founder of Pronovix, about a topic that's become increasingly relevant in the past several months: how to deal with complex, rapidly evolving landscapes. Specifically, we focus on developer portal strategies that involve finding a balance between constraints and flexibility. Too many constraints reduces your ability to adapt to uncertain changes that might require innovative, unknown solutions. Too much flexibility might not lead to any coherent, overarching story about how to use your APIs in an integrated way toward a business goal.

Audio

Video

You can also view the video recording of the same content:

Topics discussed

Here are a few questions I asked Kristof during the podcast:

  • How has Covid19 prompted companies to shift from physical proximity to digital proximity? Are APIs pivotal in the ability to make this transformation?

  • In your presentation, you talk about a Cynefin framework that has different landscapes as metaphors, including a “dancing” landscape to reflect complexity. Are we in a dancing landscape right now?

  • You mention how in complex landscapes, companies need to allow developers to adapt and modify the prescribed implementation. This is because often by the time they finish their implementation, the landscape may have already changed, introducing new factors not previously present. How does this constantly changing landscape influence our approach in documenting APIs?

  • You talked about the pitfalls of spray and pray and the need for a larger, more coherent strategy for APIs. What is spray and pray? How does having a larger, more coherent strategy compare with the strategy about embracing adaptivity and letting developers use APIs in new and surprising ways?

  • Teams within an enterprise often need to stay autonomous and nimble (like startups) to be able to move fast and pivot to meet the needs of a changing landscape. At the same time, you’ve also cautioned against organizational practices that lack a coherent strategy for how their APIs should be used to achieve business goals. How do you balance the constraints of strategy with autonomous groups that can operate independently of each other, somewhat blind to what each is doing?

Many of these talking points are based off a presentation Kristof recently gave titled The Role of Developer Portals in Digital Transformation at the API the Docs Virtual series in April 2020.

Resources

Here are some other resources mentioned during the podcast:

Kristof also wanted to acknowledge and attribute various ideas to people:

About Kristof van Tomme

Kristof van Tomme is CEO and co-founder of Pronovix, a company “dedicated to the research & development of developer portals.” Kristof and other event organizers at Pronovix recently hosted an online series of developer-portal related events called API the Docs virtual series, which has had tremendous success and reach. You can learn more about Kristof here.

Transcript

The following is a machine-generated transcript of the podcast. Expect typos, misspellings, and other inaccuracies from the actual speech.

kristof_developer_portal_strategies

[00:00:00] Tom: [00:00:00] All right. Thank you, Christoph. And for coming onto this podcast, this is kind of exciting. Um, and, uh, let's start by just kind of introducing you a bit. Um, let me, let me provide a brief overview and then you fill in the details. You are the CEO and co founder of per Novick's, uh, per Novick's as a company that. As I understand it helps develop, helps companies implement developer, portals. Uh, one of the, one of the, uh, ways you often do that is through Drupal and Apogee. Uh, you've also been putting on an API that docs virtual series, which seems to have had tremendous success and reach. Um, yeah. Do you want to add any more details to that?

[00:00:46] Kristof: [00:00:46] Um, and that's a good sum up. So, so we, um, So we are a deaf portal specialists. So we only do a developer portals, which I think as far as I know, makes us unique in the world. Um, as a consultancy, that's fully focused on just that, um, like there's products, there's some agencies that will build you a deaf portal if you ask them to, but they're used to building websites.

[00:01:11] Uh, and, um, our claim to fame is that we, we. Decided to drop everything else and just focus on this one thing and then go really deep on research, uh, go deep on community. Um, go deeper, like, you know, do, um, uh, like, uh, an award and the conference seasons and all of that stuff, just so that people can learn as much as possible.

[00:01:35] Uh, and, um, and we can, we can build better dev portals and make our customers more successful. Not the topic that I want to get into

[00:01:45] Tom: [00:01:45] today, um, has sort of evolved a little bit. Uh, you haven't, you had an earlier presentation about complexity that you, where you talked about it at a very high level, and then you, I recently was listening to your latest, uh, presentation on the digital transformation, uh, sorry.

[00:02:03] The role. Yeah. The role of developer portals in digital transformation that he recently gave in April. And I felt like you brought that much more down to earth, um, and the whole. Like COVID a phenomenon has made this topic much more, uh, like relevant, I think, um,

[00:02:23] Kristof: [00:02:23] uh, the

[00:02:23] Tom: [00:02:23] whole idea that like companies have to transform digitally in that presentation.

[00:02:28] You talked about how.

[00:02:29] Kristof: [00:02:29] How COVID has

[00:02:30] Tom: [00:02:30] prompt or the recent events have prompted companies to shift from physical proximity to digital proximity almost overnight.

[00:02:40] Kristof: [00:02:40] Yes. Can you talk a little bit about that,

[00:02:43] Tom: [00:02:43] that shift in how do API has kind of factor into this ability to shift?

[00:02:49] Kristof: [00:02:49] So I think. Uh, the way I look at what's happening today with coffin, um, is that's basically we're in this.

[00:02:58] Um, it's not super critical because that's a specific physical term, but, um, you know, when water is boil, like water is above boiling temperature, but because it's so pure, it's not boiling yet. I think that's how in the States that society wasn't. Before coffin, like we had this transition to, um, like all these changes.

[00:03:19] That's digital communication have triggered in a way we work the way we interact with people just at site Geist, um, uh, had created this States where it was not stable. And I think what covered that was, it was a catalyst that triggered that transition and suddenly it's like just boiling out. And I think, um, so people, people are talking about, you know, I don't believe that, um, these changes that are triggered by culverts, that they're going to be here to stay.

[00:03:47] And I think that's, um, it's true. That's just this, uh, this one incidence would normally not triggered it, but I think that. This is not, that's not a point. I think it is the change in society that, um, that is triggering the change and discovered as a means for triggering that change. Um, so under the digital proximity, what I mean with that, this is actually a term that was going by Matiaz bill.

[00:04:13] Uh, like we were having drinks, um, in Switzerland. Um, like I, I I've been doing this whenever I visit somebody's hometown. I try to go and have a, like a chat about philosophizing, about API APIs and stuff. And he, um, I was talking about the shift from, uh, physical proximity to digital experience and he's like, yeah, yeah, digital proximity.

[00:04:37] I was like, Oh yes, this is the perfect way to express it. And, um, basically what it practically it means is that, um, right now, if you have, uh, like my, my sister, uh, she works in a restaurant or she is married to, uh, the cook and the son of the owner and the owners and, um, [00:05:00] Uh, they were just going on their Merry business and then covert hits and suddenly they, they needed, you know, they need to survive and they need to change their business.

[00:05:09] So they started selling online. Um, they started selling breakfast and started selling lunch and a bunch of other stuff, which, which forced them to become digital first. Um, And I think this is like the more immediate aspect of digital proximity, where there's a, there's also a more hidden one, which is a little bit slower to kick in, which is the ability to be in somebody else's journey.

[00:05:31] So like if somebody has a digital product or digital interaction that you can insert yourself into that journey and being part of that without having to have like a separate, uh, user journey. So that that's, that's more or less, what's what that is about.

[00:05:44] Tom: [00:05:44] Yeah. I mean, I can definitely.

[00:05:47] Kristof: [00:05:47] Like,

[00:05:47] Tom: [00:05:47] I'm sure everybody sees this need for businesses to suddenly make their, their, their goods digital, that you can order them, that you can browse them, that they can be delivered.

[00:05:57] And how do you do that if they, if they're not in a way that can be kind of extrapolated from, uh, into some other system,

[00:06:05] Kristof: [00:06:05] um, You were kind of

[00:06:08] Tom: [00:06:08] describing this landscape. Um, and you, you mentioned a framework in this presentation called, uh, the, the

[00:06:16] Kristof: [00:06:16] citizen FMRI.

[00:06:18] Tom: [00:06:18] I, you mentioned like a mountain and mountain leading to other mountains and dancing landscape.

[00:06:23] Can you talk a little bit more about this framework and how does it help us kind of understand, uh, the situation we're currently in.

[00:06:30] Kristof: [00:06:30] So Cynefin is something that's very popular in the agile world. So I've heard people talk about presentations happening in at those conferences. Um, and basically it's a, it's a way to classify problems.

[00:06:44] Uh, according to the type, like four types or five types, really, um, they're simple problems and simple problems are like a volcano. Uh, you just keep going up, you reach the top and you're done, and it's very easy to optimize you. You don't have to understand that you just stop demise. Yeah, complicated problems and complicated problems are like a hilly landscape.

[00:07:06] And you know, when you're walking through the Hills and you might think that you're like, you just go up and you go up and I was like, Oh, there's a, there's a bigger Hill, like five kilometers away. And like, you go down again, go up against that. Oh, there's another one further down. And um, so in a complicated landscape is a, is a place or is our problems where.

[00:07:27] If you have an experts, they can show you the way to arts, the most optimal state. Now. He got, it was really interesting when you have complex problems because complex problems, they're basically a dancing landscape. So every time anybody makes a step, like I need anybody makes a decision or started doing different, suddenly the whole landscape changes and you're, you're in a new landscape and you have to like figure out like, okay, what do I do next?

[00:07:53] Um, so, and I think, and, and then there's like Celtic problems and, you know, That you paid your runaway. You're trying to somehow figure out how to make it stuff. Um, but, um, what I, I think the two drivers for digital transformation that are happening around us right now are this shift from, uh, physical proximity, traditional proximity.

[00:08:16] And the second one is the shift that I think is happening from something that looks like a complicated world. Uh, or at least in human scale is a complicated world. Biologically it's always been a complex world, but that's another story. Um, But where on the human time scales, you could kind of predict how things were.

[00:08:37] And for like 10 years who were okay, and you could have experts that knew an industry really well, and they could tell you, like, do this one thing and you're gonna be, you're going to be good. And now somehow the timescales have shifted. And we're now in this new world where things are happening so much faster, and it's so much more interdependent and interconnected that, uh, you know, Your competitor in China or somebody that you don't even know about, and China does something and it reverberates somewhere on the world and it changes your business.

[00:09:08] And this is, um, this new world that's sets like I started, this is new, a new metaphor. It's kind of like, you know, the world used to have trees. Are we, you know, we're coming in this today? We're or we used to be in a world where. Everything were plants. Like all the businesses were plants, sinners, like I'm sitting in my spot, so I'm fine.

[00:09:31] And I'm growing and I gotta re become a really big tree and I'm happy. And now suddenly animals have evolved and they've got this new nervous system and they're like running around and they're eating you all over the place. And. And, you know, what do you do with that? It's like the only way you can deal with that is he also involve a nervous system.

[00:09:52] And I think that's what's API is, are, is this, um, information infrastructure, that's acts like a nervous system to help us to react much [00:10:00] faster to what's going around us on, around us, uh, inside of us. And then also that helps us do adapt much more quickly to, um, to potential partnerships and, and, you know, stuff like that.

[00:10:13] Yeah, I, you know, it's, it's a

[00:10:14] Tom: [00:10:14] fascinating kind of,

[00:10:16] Kristof: [00:10:16] uh, it's a fascinating concept because I've, I've heard of complexity

[00:10:20] Tom: [00:10:20] for a long time and how complexity differs from complicatedness. You know, this dancing landscape, I make one move and, and the re the response, uh, Has a feedback loop that then informs my next move, which then has another feedback loop that informs my next move.

[00:10:36] It's not like a straight linear thing. We can't predict it. And each step of the way kind of requires us to reevaluate, uh, our next step. Um, now, and I think API APIs

[00:10:49] Kristof: [00:10:49] are, are pretty critical

[00:10:51] Tom: [00:10:51] illness. You had another metaphor that I really liked in this presentation. You talked about looking at API as a toolbox.

[00:10:57] Kristof: [00:10:57] Um, yes. And part of the.

[00:11:00] Tom: [00:11:00] Uh, first, if you could unpack that, but also the reason I like this metaphor of APIs as a toolbox is because it implies that people can build things with it. Uh, when, when a manufacturer salespeople

[00:11:12] Kristof: [00:11:12] hammer,

[00:11:13] Tom: [00:11:13] you know, or a tool, a dremmel or something, right. They don't always know how,

[00:11:17] Kristof: [00:11:17] how it's going to be used.

[00:11:18] Tom: [00:11:18] Um, you even mentioned that. You know,

[00:11:21] Kristof: [00:11:21] we should want to be surprised

[00:11:23] Tom: [00:11:23] by how people use our APIs.

[00:11:25] Kristof: [00:11:25] Can you talk about APIs as a toolbox

[00:11:27] Tom: [00:11:27] and how, like, maybe we don't always know how there'll be used.

[00:11:31] Kristof: [00:11:31] So this concept, um, I did a presentation at a Dodger bank, uh, in, uh, in Frankfurt just before covet, just before long downs and, um, uh, I always back then, I was like, still processing all of this stuff.

[00:11:48] I'm still processing it. I'm still evolving the ideas and how I talk about it. Um, and during that presentation, I have been talking about that. We need differentiated, therefore that we can't just make this flat interface. And, and then think that it's going to be ground like, um, uh, you know, your Def portal should be like a, uh, either a high streets shopping streets where it's lots of boutique experiences for different audiences or at least a shopping mall with different shops, insight now with different experiences and, um, and Martinez Fischer from, from dr.

[00:12:21] Bunkie was like, Oh, a key. He came back and he's, he's an awesome guy. Yeah. He's like, Oh, I'm like, I've been thinking about this and you know, it's like a toolbox. It's like, you know, you have like different compartments and you take them out. And then there's different tools that are grouped together. And I love, I love that idea, um, because also resonates with, uh, something, um, that, um, uh, uh, dr.

[00:12:46] DX has been telling me before, um, It's um, yeah, I already the long story, but, um, where, uh, this idea of, um, building blocks, um, and, uh, how API that are work together, you need to like group them together and explain them together. So you have live tutorials, uh, about, um, a set of API APIs and, and, and you know, that that's way.

[00:13:15] Uh, so that's, it it's like. If I think there's this misconception today that, um, you can make like an API marketplace and like, and that's a good concept, but the problem is that when you tell that to management and they hear marketplace, they think flea market where everybody gets the little stands and it's kind of like the same.

[00:13:42] And I think that creates this. This idea that, you know, if you can just make a uniform interface for all these API APIs that you're going to be grounds, and now you're going to get a great developer experience and that's completely wrong. Um, because you have different types of audiences that need to interact with APIs.

[00:13:58] You have, uh, people that are highly technical that need to interact with APIs. We also have people that are really not technical at all that needs technical affordances to be able to build these kind of technical journeys that they need for network. And I think that this is the shift that's happening and that is necessary.

[00:14:18] Yeah. Uh,

[00:14:19] Tom: [00:14:19] I mean, this brings up a really big and, and, and

[00:14:23] Kristof: [00:14:23] top a topic that's difficult to kind of wrangle

[00:14:25] Tom: [00:14:25] this balance between constraints. Like you would see in a digital marketplace where you're very, like, constrained about what you can do, how you can implement something, the requirements and limitations versus on the other end.

[00:14:39] Too much freedom and like, Oh, here's the reference docs build what you want. Right. Kinda like, like to throw it in another analogy. Um, uh, Legos. My, my daughter was just asking me for Legos the other day. And when you browse Lego kits, you can buy a Lego set that will allow you to build like a spaceship or, you know, a, a specific scene.

[00:15:00] [00:15:00] Kristof: [00:15:00] But the fun

[00:15:00] Tom: [00:15:00] part about Legos is. I don't want to build that scene. I can build something else with them. Right? So this balance between, Oh, there is a big picture. We want you to be able to build this spaceship, but if you want to just take them all apart and build your own, like, I don't know, Rover or something else it's it's available is that, is that balance between constraint and flexibility.

[00:15:23] Key to adapting in a landscape that's

[00:15:26] Kristof: [00:15:26] dancing. I think so. And there's a book that I thought was, uh, super insightful in that I need to look up the title, but it, um, basically the core concept of that book was that, um, life is about constraints and that it's the constraints it's because there are constraints that you can perform work.

[00:15:52] So for example, if you have an arm and you take away the bone. Which is a constraint for the muscle. They can't perform work. It's just like flubber. Um, and it's, it's because there are bones that are constraining the muscles that they can perform work. So whenever you look around, you'll see that, um, it's not the like affordances are really well chosen constraints that prevent you from making mistakes.

[00:16:20] And I think this is one of the, this is, um, Um, I think this is, this is one way that efforts, uh, API is explained that I thought was really interesting was that in the soap era, you had this super connected scum, complicated mess, where you have to define everything in your, in your calls. And it was so interconnected.

[00:16:43] That's. Anything you did, you could easily make mistakes. And an API worlds were, uh, constraining it more so that you can't make mistakes. And the key, the key advantages, like even Lego, if you, if you think about Lego, you have very specific bricks. They're very specific size they're hacker constraint. Like they're, they're exactly the same size of affordances that they can click into each other.

[00:17:09] And it's exactly this constraints that allows you to be so creative. It's the same with creativity. If you, if you need to write, if you need to tell a story, it's much easier to tell a story if your constraint and does it's like an intuitive actually. But if you're, if you're asked to say, I don't know, 20 animals, it's harder than, uh, if you are asked to, to, um, um, mention 20 mammals for example, or something like that.

[00:17:38] Okay. So, so constraints help us to be more creative and productive and, um, Yeah. Yeah. I've

[00:17:45] Tom: [00:17:45] definitely seen the whole constraint. Uh, the layout just on my blog. Like I know that if people start a blog and they don't have any topic to kind of give them focus, it's

[00:17:56] Kristof: [00:17:56] actually harder to write

[00:17:58] Tom: [00:17:58] when you, when you don't have like a theme you're tracing, uh, you know, having some constraints gives you lots more ideas in a paradoxical way.

[00:18:06] I'm trying to think of another application where, where this balance comes into play. And I'm thinking of like, Uh, let's say,

[00:18:14] Kristof: [00:18:14] let's say you've got like

[00:18:15] Tom: [00:18:15] a, an in app purchasing type type of API that lets people make transactions to buy things. Let's say you create some app and allow people to make payments.

[00:18:24] Um, and that sort of thing was

[00:18:27] Kristof: [00:18:27] probably

[00:18:27] Tom: [00:18:27] designed to function in an app store. Uh, under, you know, very specific requirements about how it work. Then you have other things come along like fortnight that says, I don't want to be in an app store. And these other games of say, I'm not giving, you know, 30% of my revenue to Apple or something.

[00:18:44] Uh, and they start just going off on their own. Now this API, if it were too highly constrained, only function within an app store, it's kind of dead in the water. But if it has some more flexibility, maybe it allows them to accept payments outside of an app store. That kind of thing.

[00:19:01] Kristof: [00:19:01] Uh,

[00:19:03] Tom: [00:19:03] that, that balance seems very difficult because how do you even know that that phenomenon are going to happen?

[00:19:08] Like, like Fortnite suddenly saying we're done with app stores.

[00:19:13] Kristof: [00:19:13] It's um, I think this is sparkly. This is the well, I, uh, another philosophical concept that I really love is, uh, finite and infinite games. And there's this concept in the world that are today from an economical perspective, we look at a world as, uh, you know, transactional, uh, you know, winners and losers, um, you know, competition and stuff like that.

[00:19:42] Um, but there's another way of looking at the world as like an infinite dance where, um, You're not trying to finish your interaction with someone, but you're trying to keep it going as long as you possibly can. Where, um, instead of trying to win the game, we're [00:20:00] trying to keep playing the game together.

[00:20:02] And I love that because this is also how I like working with our customers is that we, we try to build really longterm relationships rather than just wind a deal and, you know, onto the next one. Um, and I think. When you were in that kind of world, when there's sufficient diversity, um, then it can be placed for all of that, that can be placed for people that are working in the app store.

[00:20:26] It is going to replace for people that are outside of it. I think you, you might not be able to foresee everything that will happen, but if you can create diversity. And you can, uh, maybe through your API APIs actually allow for an ecosystem of people there that are doing the diversity for you. Um, then you, you, you might be able to adapt to things that you didn't even know that was going to happen.

[00:20:52] And the key is stats. Um, if you look at life like living systems, it's not that there's one winner. It's not the survival of the fittest. It's survival of the sufficiently fit. And it's always, um, a collaboration and, uh, this creative interaction where multiple players can play together and expand the markets and expense the value space to get her.

[00:21:18] Uh, and then, you know, and we're constantly dancing on the dancing landscape and, you know, w we can't, there's no solid grounds. Everything keeps changing. Um, yeah, this is, this is such a different

[00:21:30] Tom: [00:21:30] perspective than I think a lot of. Technical communicators have sort of been trained with. Um, usually we, we get a product and the first thing we want to do is the task analysis to know exactly who, the users, how they gonna use it.

[00:21:45] What's what are the steps to actually implementing that? Give me the picture, you know, how's this thing supposed to be used? Um, we don't really think about like, Hmm. It could be used in lots of different ways. And we don't think about like, Diversity of implementations. We think about simplicity. Uh, what's the most straightforward, easiest way to implement it in the way that the project product team designed it.

[00:22:10] So it's totally different way of sort of thinking. I want to come to another theme. You were talking about a lot in your presentation. You, you talked about this pitfall, uh, that many. Develop a portals

[00:22:23] Kristof: [00:22:23] make

[00:22:24] Tom: [00:22:24] with a spray and pray kind of a strategy where basically, as I understand it, um, people develop an API and they just kinda throw it onto the developer portal and, and walk away.

[00:22:38] Uh, and there's no kind of inter. Dependence or relationship or larger strategy about how it's supposed to be used with other API APIs.

[00:22:45] Kristof: [00:22:45] Can you talk just like

[00:22:47] Tom: [00:22:47] what is spray and pray? Why is it something to avoid?

[00:22:51] Kristof: [00:22:51] I think the, I think spray and pray is the direct result of an API or an organization with APIs that doesn't have an API strategy and unlike, and, you know, it's very easy to, to be black and white and.

[00:23:07] To some extent you have to evolve your strategy and you have to like throw a couple of things. So, um, through the wall and see what sticks, but I think, um, There's this misconception that is being created by, by the API marketplace concept or, you know, this concept of the flea markets where I can levy a tax on transactions and I'm going to get rich, which is never the case anyway, but, um, Um, there's this concept that has been, uh, sold to, um, to business owners.

[00:23:42] So on what they're, where they're expecting is like, okay, where are we going to do this API program? We're going to take all the API from the organization. We're going to put monetization on it. And now we're just going to make money. And, and, and like, and then basically what you get is this interface where every there's like lots and lots of API APIs that are undifferentiated.

[00:24:03] Um, uh, often naming might be a problem and it there's no real strategy about who you should be targeting with. What's kind of API. APIs is just basically one long washing list of things that maybe might work on maybe might not work. So now I think I see quite a lot of that and I think that to, to get well it's the first thing is to get your organization to adopt API.

[00:24:29] Make that work, but then as a next step, you also need to think about like, what is going to be the business alignment. Just your, your goal cannot be to have a lot of APIs. It has to be, um, differentiating different sections of your API strategy that fulfill business goals. Like you might have a couple of API platforms that enable a specific, um, new economies or, or, um, communities.

[00:24:56] Uh, you might have, uh, an ecosystem, like an internal [00:25:00] ecosystem. You might have like very. Simple affordances for non-developers so that they can do things that are technically challenging and stuff like that. Um, I think that's, that's how I look at it. So, you know, this is a, uh, a topic that

[00:25:18] Tom: [00:25:18] kind of strikes near to my heart and I haven't really figured it out,

[00:25:21] Kristof: [00:25:21] figured out how to,

[00:25:23] Tom: [00:25:23] how to solve it, but, uh, I feel like I'm, I'm in a position.

[00:25:27] And I think many tech writers in a similar position who are working on developer portals, where we support a lot of different independent autonomous teams. Um, a lot of companies these days are like giant companies with little startups everywhere because in order to compete. In this landscape that keeps shifting, you need to have small, autonomous, agile,

[00:25:47] Kristof: [00:25:47] exactly

[00:25:47] Tom: [00:25:47] Reddit owner teams that can be quick and make decisions and execute.

[00:25:51] Right.

[00:25:52] Kristof: [00:25:52] But the

[00:25:52] Tom: [00:25:52] consequences that then

[00:25:53] Kristof: [00:25:53] there's lack of communication there, like

[00:25:55] Tom: [00:25:55] cars driving without communicating with other cars and you hope they're kind of driving towards the same direction, but sometimes they're not, you know,

[00:26:03] Kristof: [00:26:03] uh, so this seems like a, uh,

[00:26:10] Tom: [00:26:10] A dilemma. If you want to compete, you need to have small teams, small autonomous teams.

[00:26:15] But if you do so then you end up with spray and pray where you don't have a larger coherent strategy where things are harmoniously fitting together, uh, from the, from the perspective of a top down vision, which then gets us into this other part of complexity theory about like emergence, um, I don't know if you have any thoughts on this balance between small teams versus larger coherent strategies, and maybe those coherent strategies just emerge intelligently

[00:26:42] Kristof: [00:26:42] on their own.

[00:26:44] So the way that we're trying to address this right now, like, and this, this is a new shift in the landscape that we felt like this year that we really started seeing is, uh, we have large players that come to us that ask and that they want like a central API marketplace, where they are gonna have all their APIs for discoverability and findability purposes.

[00:27:05] You also have individual teams that have their own little deaf portal that could be. No for to start, it could be just a copy of some sort of stock micro-sites, but then that they can then further evolve too, to make it that almonds to adapt it's to the experience that they need for their specific audiences.

[00:27:24] So you can like target different types of audiences where kind of like boutique experiences. And this is what I mean with the, the high streets with, um, little boutique shops kind of experience where, uh, you can, like when you go and look for APIs from company XYZ, you do find the main portal where it's all the API is together.

[00:27:45] Um, but then it points you to a bespoke experience that might be. Better geared towards, um, the different kind of, um, user journeys that you might need for certain type of affordance. This is, this is what we are currently working on, and this is, uh, I'm really excited about it because, um, like we see this where the, um, large companies that need to adapt to regulatory constraints and local markets.

[00:28:08] We see some of this, uh, we see some of this, um, Maybe in large companies where they want to build like API products and some more bespoke experiences around this. And then, yeah, I think you, you need to balance, you need to balance between, I think the main reason for having a central portal. Is discoverability and findability.

[00:28:29] So you need to make sure that all your APIs are discoverable and find-able make sure you have one interface for all of it. But then you could also think about the contents, infrastructure and information architecture to give that a little bit more, um, freedom, like, um, one of our customers call it a federated approach where you have like a federated, a Federation of deaf portals when, um, and like one, one deaf world to rule them all.

[00:28:55] Um, maybe even where it's a governance systems in place and stuff like that, but then you have these smaller enough portals, uh, that, that can also be owned by, uh, by, by one team, uh, so that they can yeah. Adapt foster to, to the local circumstances.

[00:29:12] Tom: [00:29:12] Huh? Um, uh, I like the boutique metaphor in the mall. It's like a, it's like we keep making metaphors.

[00:29:19] Right. But a and M that again, uh, highly describes my scenario, like our, our developer portal, where I'm at, uh, in order to try to like appease the different teams with their own. A sense of autonomy, uh, has led us to make a lot of different micro sites where they can choose their own header footer, and they kind of control their own little space within a larger mall.

[00:29:44] Um, And, you know, as tech writers, we help different micro site

[00:29:50] Kristof: [00:29:50] teams,

[00:29:51] Tom: [00:29:51] uh, published. Sometimes we don't, they just publish on their own. But I think the realization now is that

[00:29:58] Kristof: [00:29:58] it's

[00:29:58] Tom: [00:29:58] sort of a hodgepodge [00:30:00] experience from one microsite to the next, like a mall, right. It's like, wow, you go and you see one store, that's got like a complete hipster vibe and another, that's got like a modern, urban vibe, others that are like, uh, uh, uh, Discount shopper vibe.

[00:30:15] Kristof: [00:30:15] Um, you know, is this a

[00:30:17] Tom: [00:30:17] bad thing to allow this diversity? I mean the worldwide web is just, uh, a miscellaneous grab bag of different styles. Does it work for a company or is that bad?

[00:30:29] Kristof: [00:30:29] I think it depends on how you approach it. I think if you have, um, if you have to bright constraints, Yeah around this, um, then, uh, probably can allow for adaptivity.

[00:30:47] I think this, this is, this is the, this is the learning of complex adaptive systems is that you, you need to create the system. That is adapted to its environment. And then you need to trust that the system will perform properly and like, you didn't have to let it do its own thing. And, and then sometimes it will fail.

[00:31:08] Sometimes they will succeed and then they will learn from it. And it's just the key is the learning. Like we have a, one of our oldest staff portal customers. Um, they did this. Fantastic transition from a pure product company to a, like a significant portion of their business being API. And, uh, they, uh, basically to have different people responsible for different sections of their, therefore it'll like as business owners.

[00:31:40] Um, and there's like still coherence, but there's also an activity and learning, uh, that is spread throughout the organization. And I think that is the key is that you. Um, you, you cannot, I think that's a stack riders. What we need to become a, uh, an affordance that helps Otter super form work, where we enable otters to be more productive, uh, rather than the ones that are doing the work.

[00:32:11] And that are kind of like the, the, um, the gatekeeper that the information needs to flow through. Um, And if you, if you can set up the rights, uh, constraints and experiences, then, um, I think that's, yeah, that's how you can adapt and, and there's gonna be failures. There's gonna be sometimes things that are not working out well.

[00:32:35] But I think if you, if you create one single monolithic system, I think this is again about complexity. Like what, this is what we actually see when we built. When we build one single system for an organization and then there's difference. Um, different groups that have different requirements for that system.

[00:32:55] Then sometimes that means that you're building it more and more and more complex until you have this really complicated mess that that just becomes hard to maintain. So it is better to, to try to. I think in a microservice versus, um, monoliths story. I liked the idea of microservices, uh, which is basically, you know, microservices.

[00:33:16] Okay, don't go over boards because you know, you're going to have an orchestration problem, but, um, uh, but built microservices, which are chunks of functionality that fit together. Ah, fit together well, um, that are focused around a certain job. Like it's not one single job, but it's like a couple of jobs that are related to each other.

[00:33:38] Um, and, uh, and that can evolve together because it is also how biology does it. Um, our genomes, um, basically all our genes, um, like every time you build a new living being, or a new living being, uh, gross, um, all the genes need to work together with each other. And if there's a, if there's something really wrong, then it just fails and that's a creature that will not be, um, and it's.

[00:34:08] So it's almost like testing that is happening life and production, but at that, that's how biology is doing it. And I think it's that's um, the coherence of constraints is what you're looking for is like you're, you're, uh, looking for the right methods to try out a whole bunch of. Groups of constraints together to see which ones are going to perform the best.

[00:34:33] And, and you can't centralize that because when you centralize it, you're not going to do the same learning. And, uh, um, yeah. And at the same time, you need to make sure that's that there's a, there's a second layer of like an emergent layer, uh, on top of that, that is still bringing all the information together.

[00:34:53] But while still allowing, uh, for, for the activity on the local level, [00:35:00] No. I had an

[00:35:01] Tom: [00:35:01] experience recently where I feel like this sort of, um, scenario really played out. Um, we were trying to define our release process for SDKs. When a team has like a new SDK, they want to push out. We realized we'd actually didn't have a formal process for doing it.

[00:35:19] Um, and so we, we started to write out a document that would say, look, you got to push. If it's a Java file, you gotta

[00:35:27] Kristof: [00:35:27] push this

[00:35:28] Tom: [00:35:28] over to J center or Maven. Cause you know, we don't want to be the ones managing it. And this makes it easier for developers. We thought, Oh, this will work. And it kind of worked with one team, but then the other said, well, you know, uh, Like our stuff, isn't always a jar file.

[00:35:46] Like it doesn't fit in that, in that scenario. And others had like open code that would fit better in get hub. And others were like, well, this is a cost prohibitive. Due to the licensing for enterprises, for us, you know, we just want to have our file on an S three bucket.

[00:36:04] Kristof: [00:36:04] And so it was like, you know, we tried

[00:36:06] Tom: [00:36:06] to think about, Oh, let's

[00:36:08] Kristof: [00:36:08] have a top down policy.

[00:36:09] This

[00:36:09] Tom: [00:36:09] is going to be how

[00:36:10] Kristof: [00:36:10] this will be, how everybody

[00:36:11] Tom: [00:36:11] releases their STKs. And it just falls apart without that flexibility. Right.

[00:36:15] Kristof: [00:36:15] And I feel like technical writers were often

[00:36:17] Tom: [00:36:17] caught in this, in the middle of all these different teams trying to publish onto the developer portal. And we have to figure out well, Do we let team a do it like that.

[00:36:26] Whereas team B does it like, like that in a different way? Do we try to federate some

[00:36:31] Kristof: [00:36:31] kind of

[00:36:31] Tom: [00:36:31] standards? Cause you know, at the same time you don't want just. Everybody doing their own thing. Uh, you want to have consistent terms and styles and you want to have, you know, some kind of federated search.

[00:36:42] Kristof: [00:36:42] So it's constant

[00:36:43] Tom: [00:36:43] sort of interplay between, uh, standards and flexibility.

[00:36:48] It's uh,

[00:36:49] Kristof: [00:36:49] It's interesting space. I think this is what life always does. It's always this creative tension between two opposing things where you can't go to the full extreme on either of them. That's always like everywhere to look. This is where, um, where the kales of life plays out. Uh, and I think this is, this is just sort of another repeat of that pattern that we're seeing in business.

[00:37:14] Um, it's, um, And there's like different forms of fits that will survive. And that will be okay. And maybe even be productive. Um, but then you have to like leave space for, I think, I think it's often about creating space. And one of the key things I've learned as a, as a manager is that, um, If most of the time, all you need to do is create space for people to grow and to become.

[00:37:44] And, um, and I think it's something similar. Like I know Lawrence, um, his handle, this API handyman, he has this, um, he did this stock abouts API like governance. And because he's like the mr. API at his company and. Uh, basically what he said was I realized that we can't just dictate, like we can't just dictate a policy because people would come with the design that I was like, what the hell are you trying to do here?

[00:38:18] And then I said, I would have a talk with them. And in return outs that actually, it totally makes sense. And like I learned something and I think, I think that's the, um, I like this from a book from, um, Oh, anyway, I'll give you the list after, after the multicast, but I'm a book about its complexity and managing in complexity where, um, They said that dealing with change management and helping organizations to evolve in, in a complex environment, you have three mechanisms.

[00:38:54] You can change the container, like change the team size or team, team group, or are like what kind of teams you have. You can create a super team or something like that. You can create meaningful interactions. Um, like M and R or yeah, like you, you have this transformative interactions where you are discussing with people, or are you creating, you're creating conflicts almost where people are learning through those conflicts.

[00:39:23] And then the last one was sweet, calm, uh, containers, transformative interactions. And. Meaningful differences, having diversity and creating space for diversity. Um, and if you, if you change any of these three year system will start adapting and become more adaptive. Um, and, uh, and I was, that was a really interesting, um, so I like this, this is one of the writers and the, look it up for you.

[00:39:54] Tom: [00:39:54] Hey, you know, you've, you've read a lot in this, in this area. I know your previous [00:40:00] presentation that I was also mentioning was more, that was more conceptual. You had like, I don't know, six to 10 books or something on this topic that you've been reading into.

[00:40:09] Kristof: [00:40:09] Yeah, that's I now during covert, I'm reading a lot less.

[00:40:15] Um, but I. Yeah, I like being exposed to new ideas and, uh, are looking for new patterns that, that, that I can then bring back to the business. Uh, it was, um, um, organizational weights, uh, Facilitating organizational change by Edwin Olson and Glenna , um, was really, really good book. I love that one. Yeah. Well,

[00:40:45] Tom: [00:40:45] we've been chatting a lot about these topics and I'll, I'll link to the presentations and other resources.

[00:40:49] You've also written about this. Um, and you, you,

[00:40:53] Kristof: [00:40:53] uh,

[00:40:54] Tom: [00:40:54] I just have one more question kind of that I'm hoping you can. Share this API, the docs virtual series is one of these new things that you guys had never done before. Right? Nobody had ever done a virtual series like this and the format you've done hybrid format.

[00:41:10] And, uh, you know, with the online presentation followed by interactive Google meet, followed by podcast and recordings and so forth. Um,

[00:41:20] Kristof: [00:41:20] How has

[00:41:21] Tom: [00:41:21] it played out? Do you have like more, more viewers than at a regular one day API, the docs conference? Or is this something that after Kobe was over, it's like, yeah, we're going back to our old format.

[00:41:33] Kristof: [00:41:33] So it's been very interesting, like, because we were really early with this, um, like w w the moments, even before the log downs, we were like, This is changing everything like bow, what are we going to do? And then, uh, like we, we closed the company, the office before, uh, lockdown started. And, um, and then also like fairly quickly, we were like, we're not going to be able to do our conference.

[00:42:00] And now we were like, okay, what are we going to do instead? Um, and because we were so quick with launching this, we actually saw a growth of 20% in our mailing list. 20%. This is a mailing list. We've been billing for, uh, five years now in one month, which is crazy. And I'm also like, are, are the people being present?

[00:42:26] Like we, we normally sell out a 250 seats, uh, like, because we have, like, in the first season we had a limitation, our technology, the number of people that could, could attend, um, And, um, yeah, so, so we, we are reaching more people. Um, I think we are, we've been having a more meaningful impact. I, I think that there's still as something for physical events.

[00:42:52] So I think we will, uh, I don't know yet exactly how we're going to do it, but I imagine that maybe we'll be doing both. Um, cause I like that this is democratizing access, like, eh, Anybody in the world can canal and, um, you know, access to events, which is great. And you don't have to have the money to fly into Europe or, or do you S or, you know, uh, or wherever we were organizing it.

[00:43:17] So to be able to attend, and that's great at the same time, the experience is different, and we're still looking for a better technology stack. Like there's some new tools. Um, but I don't think that, um, The same serendipity and the same emotional connection that you get from a physical event that you can get that from a virtual event, it's much more fleeting.

[00:43:38] And, um, yeah. And so it's, I think. Yeah, there's good in both. And again, it's about adapting. It's like, if you're, if you're quick in adapting, any problem can be, um, can be a resource, uh, your biggest problems become your biggest resources. Um, and it's, uh, yeah, it's always been like that through, throughout my career and it becomes more and more like that actually.

[00:44:07] Well,

[00:44:07] Tom: [00:44:07] it's definitely cool to see you guys experiment with different approaches and technologies and to see what works. I personally have been sort of watching it especially closely because I've been trying to figure out how can I make my API workshops that I've been doing that we're in, in person one day, something that actually works online.

[00:44:24] So I've been kind of observing and you know, what do I like? And. It's hard. And I think as you say, you have to experiment and adapt based on the feedback that's coming in to figure out a different strategy and, and the landscape is changing. You know, I can barely even, uh, have any confidence about planning an event two months into the future, because I have no idea what's going to happen in two months.

[00:44:47] Maybe, maybe it's all back to normal. Maybe we hit that second wave. And like it's five times worse.

[00:44:53] Kristof: [00:44:53] It's

[00:44:53] Tom: [00:44:53] like very difficult, which it just underscores the whole, like. Dancing landscape, maybe [00:45:00] dancing is too kind of a word, right. Is to

[00:45:02] Kristof: [00:45:02] unite delight and

[00:45:04] Tom: [00:45:04] so much of a nice image, you know, just sort of like the dancing lava or something.

[00:45:08] Kristof: [00:45:08] So yeah, definitely that same level too, like today. Yeah, for sure. I think it's um, yeah. One thing I firmly believe in that I've seen through like, Oh, it happened over and over again in my career is that I would have this long standing problem that I cannot figure out how to solve and then comes around.

[00:45:31] Not a problem. And suddenly the solution becomes apparent for both the new problem and the old problem, and they cancel each other out and I have this over and over and over again. So I think that the key is to, um, to not to see obstacles as something that is limiting you, but as a trigger for creativity, like how are we, how are we going to respond to this so that we can increase the value that we provide?

[00:45:57] And this is, this is what we basically said is like, so how are we going to help our community to get through this thing? And, uh, and two things came out of that. One was like going digital with API docs and, and also the, the podcasts that we start at API resilience, which is basically about telling the stories about, um, you know, telling stories about teams, where the business has decided to continue investing in digital and in APIs.

[00:46:27] And, uh, and dev portals and documentation. And, um, uh, so that's our, our community has those stories that they can go to their managers with and say like, you know, don't cut my budget because you're gonna be really sorry in five years. Um, and that's, that's kind of the, the, the idea. And then, and if you, if you look for what is the ma, how can I maximize the value that I can create in the world?

[00:46:55] Um, And there's all like, you need to be a bit savvy and you know, you can't give everything away, but, um, uh, normally there's always a Boff that's guides you to your next thing. And then, um, I, so I think, I think that that would be the, what, what would digital workshops enable you to do that you otherwise can't do?

[00:47:17] Um, like there were, I listened to a podcast from, um, a couple of sales guys. And they basically started a virtual events where it had a lot more people attending at a lot, lot lower tickets rates. Um, but they could afford it because it was just, you know, you didn't have to go physical. There was a bunch of things that were different because of which it became possible.

[00:47:40] Uh, so I think, I think that that would be my advice, um, the, to deal with that problem.

[00:47:46] Tom: [00:47:46] That's a good, that's a good perspective to have, right. Instead of seeing the challenges as like roadblocks and obstacles, opportunities to like, uh, do things in a new way or different way, or what can we do differently?

[00:48:00] You know, as you said, what can we do differently in this new medium that we couldn't do in the past? How can we exploit it for a better result? Um,

[00:48:09] Kristof: [00:48:09] it's also like the, um, everybody is getting those roadblocks. If you're the first to adapt you're way ahead of the game. So if you're, um, so every obstacle literally is an opportunity to grow your business and to become stronger.

[00:48:29] Uh, actually life thrives from obstacles. It's our long history of obstacles that has brought us where we are today. Um, yeah. One

[00:48:41] Tom: [00:48:41] other interesting thing, uh, is that

[00:48:43] Kristof: [00:48:43] given

[00:48:44] Tom: [00:48:44] that everybody else has basically canceled their event, you know, whereas you went forward, it's like suddenly everybody had attention for your event, right?

[00:48:52] Like

[00:48:53] Kristof: [00:48:53] everything else is canceled,

[00:48:54] Tom: [00:48:54] but Hey, here's API that talks and I got nothing else to do. So, uh, it's like a. Perfect opportunity.

[00:49:00] Kristof: [00:49:00] I it's, it's flipped again now. Like now there's so much events it's changing again. So our, our next move is we're going to be more focused still. Like we're thinking about, um, topic XYZ in, in, um, markets, um, ABC or something like that, so that we have like hyper-focused defense.

[00:49:25] Now are really irrelevant for one or two audiences, uh, to, um, uh, to keep people, you know, that if at least they come for one of the occasions, if they don't, if they don't have the time or the energy to be there for all of them.

[00:49:41] Tom: [00:49:41] Yeah. Well, uh, as we wrap up, is there any topics you wanted to cover that we didn't or did we cover everything?

[00:49:48] Kristof: [00:49:48] Uh, I still want to do a shout out for Christiana betta because I, I call that dr. DX and that's that's Christiana betta, and to Robin Meisner. And it's a Christian about her works at box. He's a [00:50:00] dev REL, um, guy. He's awesome. He's got some interesting ideas around developer experience and friction. Um, the friction lock comes from him.

[00:50:10] Um, And Robin Meisner who works at Tuohy, um, who gave me this, um, analog of, of, uh, API APIs as, um, like, like soap, but things that don't let you fail that limits you from making failures. Uh, I don't want to attribute those to, um, otherwise I think, um, But that's a whole other podcast. I got to another topic.

[00:50:38] Well, I know you probably know.

[00:50:43] Tom: [00:50:43] And just a listener know, like all these questions I'm asking Chris stop. I didn't, I didn't give him any of these questions ahead of time. I had, we had a whole other sort of previous script and I was just like, I just kind of threw that out the window and went with this other direction.

[00:50:57] So like, you're, you're able to speak on a lot of different topics extemporaneously without much preparation, because you're such a deep reader and thinker. So that's definitely a good thing.

[00:51:10] Kristof: [00:51:10] I'll be Kristoff. How do people get,

[00:51:11] Tom: [00:51:11] how do people find and reach you? Like if they want to follow you on Twitter, if they want all that shit, like know more about.

[00:51:17] Any per Novick's or API that ox, where should they go?

[00:51:21] Kristof: [00:51:21] Um, so I'm, at, uh, on Twitter. Um, So Christophe is my first name and is my family name. And it's a, it's a Dutch name, double M E um, our company you pronounce it perfectly, which is a wonder, because most people will just completely mangle it. Um, Uh, so if, if you go to dot com, you can find more about our business and the work we do, and therefore we'll space.

[00:51:49] And then, um, API [email protected], and the deaf portal awards is at deaf portals. And therefore Lavard still to Oracle. So, uh, so have a look at those and they're interconnected and landscape and, and yeah. If anybody wants to have a chat about any of these subjects, I'm always game. Uh it's uh, yeah.

[00:52:12] Great.

[00:52:13] Tom: [00:52:13] Well, thank you so much. Thank you so much for coming on the show or having this conversation with me. I really enjoyed it.

[00:52:19] Kristof: [00:52:19] Thank you for the opportunity. It was always fun. It was a really good chat.

Buy me a coffeeBuy me a coffee
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,500+ subscribers. (See email archive here.)

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer based in the San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.

Comments