Made by
Made by
After transitioning to dev rel from backend development, Avital Tzubeli became the first developer evangelist at Kaltura. In this talk from DevRelCon San Francisco 2019, Avital outlines the importance of developing relationships and negotiating team dynamics when creating effective developer resources.
It’s December 2017, it’s where our story starts. I am unemployed and I make a grand declaration. I don’t want to be a developer anymore. A bunch of you have probably done the same. And so I run around to a bunch of product manager, project manager, success architect, customer success interviews, and none of them are hitting home.
And so my confidence in this big decision gives way to slight desperation and I post this on Instagram asking my friends for help. What I’m holding in my hand there is a plate of homemade hummus, not “hummus,” hummus, which I had decided to make with my friends one night for fun, since I know how much dev rel folk love recipes. Here’s the recipe for homemade hummus. The trick here is to be really patient and let the chickpeas soak for a really long time.
Anyway, this post gets me a Python interview, which isn’t what I wanted, but old habits die hard. And the interview was terrible, but that’s not the point. The point is what happened afterwards, which is that I bumped into my friend and her coworker who looks me up and down and says, “But you don’t look like a developer.” And I say, “I know.” And he says, “Well, I don’t know what you’re looking for, but my previous company is looking for a developer evangelist.” “Excuse me. What?”
And I do my research, and in fact, this job description looks like it was written just for me, and I aggressively send my resume through every single connection I could find to the company. Much, much later, I found out that the guy I was seeing at the time swims daily with the President. Granted a swimming pool is not a great place to share a resume because it would get wet.
A few days later, I meet my future boss. The next day, a Thursday, he sends me an email with a three-part assignment of which this is number two, create a video showing how you build an iOS app using Kaltura. Now, I read this and I read this again and I read it again and I panic because not only had I never touched mobile development, I was a backend engineer, I also had to create a video to capture how ignorant I was. But I was determined to do so by the end of the weekend because I was terrified somebody would beat me to my dream job.
This is way before dev rel was a thing in Israel, so I just didn’t know anything about this space. Luckily for me, Tel Aviv is facing our worst storm of the season that weekend and so these beautiful beaches that you’ve probably heard about look a lot like this in preparation and I have nowhere to go this weekend except for my computer screen.
And so picture this, it’s dark, it’s stormy. My Wi-Fi is down because of the storm. I’m sucking all of the life out of my hotspot in a rush to learn iOS development and create this video. By the end of the three days, my mobile provider blocks my data usage. But I have this really awkward video of myself showing off my new iOS skills, which I then send along to my future boss with my comments and criticism about the API, to which he eventually says, “Great, that’s your job now.”
Fast forward, I am Kaltura’s first and only developer evangelist. And if you think that elevator pitch is hard, try doing it in Hebrew. It’s way harder.
To tell you a little bit about what Kaltura does. What you need to know is that at its core, it’s an API with a bunch of video capabilities on top of which we build all of our video products. These are things like a private YouTube that we call MediaSpace, which is used mostly for internal corporate training, or some classroom tools for universities.
And a little separately from the API, we have what we call our Player. Now, this is something you touch every day. You probably don’t really think about it. It’s the frame in which you watch videos. It’s got the play, pause button, seek bar, a bunch of other buttons. And that’s exactly what we’re going to be speaking about today.
Now the Player at our company has its own elite team, their own open space, their own reputation. It’s built in native code, which means you can easily embed it into HTML or mobile apps. And that’s exactly what I was doing in my interview without really knowing the difference between using the Kaltura API and using a Kaltura Player because all of the API documentation was lumped into the same place.
So I started my time at Kaltura working on the API portal, documentation, tutorials, moving everything into our new developer portal. And after a year of working on this, my boss turns to me and says, “Hey, remember that really awkward video with the short hair that you created for your interview?” “Yeah.” “It’s time.” Except he didn’t say like this. I just recently watched “Lion King” and it’s very fresh in my mind.
So what would the Player documentation entail? Well, for starters, we had just released Player v7. We were trying to get people to use that instead of Player v2. Obviously, 7 comes after 2, but we have to maintain documentation for both. As I mentioned, the Player is native to Web, iOS, and Android, so we’d have to have all these three segments.
And here’s the real kicker, all of the documentation was split in a hundred different places, all the existing documentation. And so, needless to say, I’m overwhelmed. We have this preliminary meeting with the Player team to tell them our plans to create this Player portal. And everyone’s really excited, but the Player team has a few issues.
First of all, they want their own portal, their own domain. The Player is a standalone thing. There is no reason it should be lumped in with the API documentation, which is kind of what I was going to do. Secondly, if it’s your domain, how are we going to update it when there are changes?
And thirdly, most of the Player customers were OTT customers. This is on-demand streaming like television, customers that have nothing to do with the API. And it makes no sense to send them to the API documentation when they have questions.
And so we went around like this in circles, the Player team wanting their own stage, my boss wanting thorough documentation for our portal, and me just awkwardly trying to make everyone happy.
And we agreed on this. I said, “Okay, fine, the Player will have its own portal,” but we would link to it from the developer portal that tab at the top. So when you click on that, you would end up at a Player homepage. All of the documentation for this would be in a GitHub repo that we all have access to so that I can make changes and you guys can make changes, and so that OTT could pull in any overlapping documentation without creating duplicates.
And this argument obviously took much longer than I just described it. And something I want to say about this is, you know, we oftentime have this picture of how we want things to look. But in times like this one, it’s kind of blurry and nobody’s obviously right or wrong, It’s a lot more important to put effort into building those relationships and kind of being a little flexible than in getting the things that you want.
And so we make this agreement and obviously, I have no clue where to start. And it would have made sense to start with Web, but I decided to start with iOS. Because when you’re lost, a good thing to do is to start with what you’re familiar with. And I was familiar with what it was like to be somebody who had no clue about Kaltura. I just want to get this Player into an iOS app. Just tell me how to get started.
And so let’s talk about this Getting Started document. What does it actually mean? In my previous life, I was a backend developer for a mobile marketing attribution company, the dark side I know and my job entailed pretty much integrating hundreds of APIs into our platform. Which means that I had the misfortune of reading a lot of Getting Started docs, or even in worse cases, going looking for Getting Started docs.
And let me tell you what I found out. A lot of people don’t understand the meaning of “started.” So, there’s this rule by this guy named Ori Pekelman. I don’t know if you’ve heard of him, I first read about him referenced by Nordic API articles. He’s a CEO and API expert, who apparently likes writing poetry in Hebrew and French, so I related to that on some level. And he coins this rule called the 333 rule.
Some of you might have heard about this. It states that in the homepage of your API, it should take a developer three seconds to understand the purpose of your API and then find the entry point within 30 seconds. And within three minutes, they should be able to create an account, call the API, and do something with that result.
Now I love this rule, I try to adhere to this rule. And I took it a little bit further with my Getting Started doc and I said the Getting Started doc should take you from negative 10 to 100. And when I say negative 10, I mean somebody, and we’ve heard this a bunch, somebody who knows nothing about your platform, they might not even be a developer, just somebody who wants to use your platform and wants to write some code. By the end of your doc, they should have everything they need in order to create a significant action against the API and do something with that.
Ladies and gentlemen, your Getting Started page is your hook. I know your homepage is a lot prettier, it’s a lot more colorful, it’s more descriptive. That’s where people might end up. But those who want to do something, go straight to your Getting Started page. And I know this because I was there hundreds and hundreds of times.
Now the problem with creating something this good is that you need to do a lot of research and a lot of learning. You want to give them the bare minimum that they need to know, but in order to do that, you can’t just know the bare minimum. You need to know all of the things in order to extract the important things.
And so I researched and I wrote and I researched and I wrote. And eventually, I wrote this doc the way I would have liked it to be a year before that when I knew nothing about anything. And I present this to my boss, and he looks at me and he says, “No.” And he calls me out for not reaching 100%. And he’s right because the Player for mobile has one caveat, and that is that it has no UI.
We state this explicitly, the Player has no UI, deal with it on your own. And so I was creating, I was demonstrating how to do play, pause features on the Player with buttons that look like this that are made of text and aren’t actually buttons, ending up with something that looks like this, which in my opinion, looks quite good, but my boss looks at it and says, “Really? What happened to your Getting Started philosophy?”
And he was right because anyone using the Player, any developer using the Player would most likely need buttons on the Player. And so at the very least, they should receive basic instructions on how to create those buttons. And it’s so easy to say, “It’s not in our product. It’s not my responsibility, sorry, deal with it yourself. This isn’t our thing.”
But those corners that we sometimes cut, out of apathy or laziness, that can be the last straw that makes somebody say, “I hate today, I hate your platform. I’m never coming back.”
And so I’m feeling kind of sheepish and overwhelmed. And I’m running around trying to figure out how to add these buttons. And I’m writing code and I’m getting stuck. And I’m writing code and I’m getting stuck. And I’m asking the Player team, and the response I’m mostly getting is, “Sorry, but the Player has no UI. Maybe you should try Google. Have you heard of it?”
And I desperately, you know, shout out to the heavens, “Is there anybody who can help me with these buttons?” Not quite so dramatically, but you get it. And someone says, “Yeah, have you heard of Leonid, he could probably help you.” And I don’t know who this person is. I’ve never heard of him. I don’t know where he sits. I sent him a message, he doesn’t answer.
The situation is dire because it’s 4:00 pm on New Year’s Eve, and no, that doesn’t mean everyone’s on vacation. It means that the following morning, we’re scheduled to start the Kaltura hackathon, which we have on New Year’s because we don’t celebrate New Year’s. And nobody talks about work during hackathon, especially not developers. And the worst part is that I’m scheduled to leave to Thailand for a remote work trip for a month directly after the hackathon.
And so any chance of getting help in person is totally lost on me. Luckily, redemption comes on day two of the hackathon when I’m using AirDrop and I see Leonid’s iPhone as one of the options and I run around looking for this ghost and I find him and he’s great, and he sends me the Player buttons and shows me how to use them. So if you ever looking for someone, try AirDrop.
Anyway, I get to Thailand, I get settled in. I add these buttons to my player. I finished the Getting Started doc and then I show them to any technical person I could get my hands on in Thailand. Because, while a lot of times you’re doing the research and learning in order to create this doc, other times, we’re actually the experts on the matter, who are writing the docs.
And we forget all of the steps that happened in between the steps that we mentioned. And we make assumptions about expertise, and background and, you know, etc., etc. And it’s natural, because we’re in that place. And so, when you’re doing something this important, ask an outsider to read the doc, read every word, do the steps, see where they end up, you’re going to find a lot of things that you missed this way.
Now, while I really wanted to continue perfecting this doc, because I had nowhere I went to go, at this point, I had to just, you know, do what you do when you have no clue where to start, which is just take everything out, like everything out, list it all out. Marie Kondo, put it on the bed, on the table, anywhere you could see it, or in my case, a Google Doc.
And I just brought in all of the docs that I could find that were relevant that were updated, and I put them in this doc and I was able to kind of see what I was working with. It became a lot less daunting. And then I was able to share them with the Player team, and we discuss what needs to be obliterated, what needs to be rewritten, and what order we want to see things in.
And at this point, I had to start really asking for a lot of help to make these decisions about what gets rewritten, etc., etc. And the problem with asking for help in this case is that it was kind of my project and it wasn’t a priority for the developers. And despite the fact that I spent every day for two months just going up to the ninth floor, which is where the developers sit, and acquainting myself with them and showing that I care, and trying to build this relationship bringing treats, eventually, I started getting invited to lunch, which is a big deal.
Still, when I would ask for help with the documents, I’d get a very sincere, “You know, I’d really love to help you, but I don’t have time right now.” And you might get this a lot and it’s frustrating and it’s annoying and how can they not understand how important this is? And honestly, I had to stop myself from making demands in the name of my boss. You should not do this. Okay? You shouldn’t do it to developers, you shouldn’t tell anyone, “Hey, this really important person has requested that you do this.” That is not how you build relationships. That is not how you gain respect.
So what do you do? Well, one thing that really helped in this situation was the idea of delayed gratification. You know, this doesn’t seem important right now, but later, we won’t have to direct all developer questions to you, because we could just send them directly to this documentation that we’re writing right now.
Another thing that really works is offering to work on it together, “Hey, can we take a few minutes and sit down and work on this? It’s really important to me.” And it shows that you care that you don’t want to just hand it off, you are invested in the success of this project. And a lot of times you’ll get, “Okay, fine, but I only have 10 minutes,” which really means 30, or they’ll say, “Yeah, but let me do it myself,” because that is the way some people prefer to work.
And if that doesn’t work, bring on the flattery. And this isn’t just about kissing up. People need to feel, people want to feel needed, valuable, appreciated, not just developers, all people. This is what we feed on. We want to know that there are things that other people can’t accomplish without us. And so if you express to someone that you are working on this thing that you can’t do without them, they will most likely want to help you. At some point, just be patient, like with the chickpeas.
If it’s not right now, it’s tomorrow, it’s the next day, especially if you’re showing your appreciation with treats. You think I’m kidding, but this goes a long way in showing effort and care, and so yes, I will be taking suggestions after this talk about which weird treats to bring back from America.
And so, after I collected all of these docs, I, you know, brought them all to my machine. I did some skimming, some editing. And then we decided to go live with just iOS. My boss wanted to start sharing it, I wanted to be able to see some progress to make it easier to continue. And I make this pull request and the response I get from Jess, who is the master of our open source and developer resources is, “You didn’t use a spell checker?”
Apparently, skimming these docs wasn’t good enough. These were docs written by Israelis. They’re absolutely brilliant Israelis. But we ended up with a lot of funny words like “situtation” and “distorying,” and my personal favorite, “expaline,” then a lot of sentences that made absolutely no sense. And we must have been in a real hurry to push this because it’s quite obvious, use the spellcheck, just do it. You would think this is obvious. So I tried one in command line. Eventually, I moved to this extension called Spell Right that I really like.
And eventually, iOS was live and I repeated this whole process for Web. I wrote the Getting Started, I copied over the docs. I went to town on them with my Spell Right extension, and I proudly submitted my pull request and Jeff says, “I thought you were using a spellcheck. Why are you still not consistent about whether you want to capitalize the word API?”
And at this point, I decided to stop being lazy and just read every single document that I was working with. Seriously, it would have saved me so much time in the get-go, instead of going back and forth with these PRs. Read every word.
Yesterday, I almost got into some woman’s red Tesla instead of my red Uber. So check your car, check your docs, every word, guys. Because if there’s one message I could take from this entire talk, it’s this, be thorough. Be thorough in your research of what it takes to get started with your documentation.
Be thorough in how you want to express your platform to outsiders, and coming off as considerate and inclusive to all backgrounds.
And be thorough in understanding the people that you’re working with and cultivating those relationships with them in a way that, you know, you can ask for help later, and it won’t be an issue.
And throughout all of this, you’ve heard this a few times, don’t forget to have fun with it. Because, yes, this is really technical, but users want to know that there is a human on the other side of all this information.
And so we created this really silly video with the production team highlighting all of the Player features. I so wanted this to be ready on the home page by the time I saw you guys, but chocolate can’t solve everything. And so if you check back within a few weeks, the developer portal would be up there with all of the iOS, Android, and Web resources.
Thank you so much. Big shout out to Simba for supporting me through this talk and, thank you.