Erin McKean is the founder of Wordnik, the world’s biggest online dictionary. In her talk at DevXcon 2017, she described how they’ve supported and incentivised beginner developers working with the Wordnik API.

Transcript of Erin’s talk

So hi, I’m Erin McKean. I’m the founder of Wordnik where I’ve also done support for our API since about 2010. I’m also the founder of the Semicolon Appreciation Society. I have more of these stickers if you would like to join. You can appreciate the semicolon from whatever distance you deem appropriate. And also, since October of last year, I’ve been a developer evangelist for IBM talking about LoopBack, which is an open-source tool for rapidly creating API’s with node. So if anybody asks you what IBM sells, please say, “API Connect,” that’s all I ask of you.

But today I’m talking about Wordnik. How many people have used, or how many people have heard of Wordnik? Oh, I like y’all. How many people have used our API? Okay, a couple hands. So Wordnik is an online dictionary. And as you can see from this sticker, we take ourselves very seriously. I also have plenty of these stickers that I’ll put on the table later. And so when people hear online dictionary, they usually think of something like this. Let’s just burn some text speak into the traditional dictionary. And so, yes, Wordnik does include words like OMG and LOL. And we think they’re perfectly cromulent words. I like you all even more because you laughed at that. But the mission of Wordnik is to find and share all the words of English.

Now, this is harder than it sounds. Because it turns out that the majority of the unique words of English are not in traditional dictionaries. You do not have to take my word for this. There was a paper published in the Journal of Science in 2010 where they looked at the Google Books corpus, so about 5 million books, about 4% of the books ever published. And they looked at every unique word, and they found that 52% of them were not in traditional dictionaries. They also estimated that the English language grew by 33% in the 20th century alone. That is a lot of words.

And so at Wordnik, we are collecting these words, and you can look them up. And the main use case for the Wordnik site, is people trying to find information about one of these dark matter words, one of these undictionaried, missing words that’s not in a traditional dictionary. I’ll give you an example the word zemblanity, does anybody know this word? Okay. So zemblanity is the opposite of serendipity. Yeah, serendipity is finding happy things by accident, and zemblanity is finding unhappy things by accident.

I think software developers encounter a lot of zemblanity in their lives. Have you ever been fixing something and you’re like, “Oh my God. It’s problems all the way down.”? So yeah, zemblanity, so this is the kind of word that doesn’t tend to show up into traditional dictionary, and we try to find these example sentences which you probably can’t see that serve as dictionary definitions and so we’ll show a word even if we don’t have a traditional definition. And we have a lot of metadata about words. So, for example, the word hagiothecium has been looked up over 1600 times, has been favorited once, is on five lists has 24 comments, and is not, I regret to inform you, a valid Scrabble word. And if you’re painfully curious right now about what a hagiothecium is, it’s a small traveling case containing small plaques painted or carved with Byzantine style portraits of saints, very useful. That’s explained in one of those 24 comments. But what does that have to do with developers? Unless any of you were carrying a hagiothecium today. No? Okay.

The other thing that Wordnik does is we provide an open API for getting data about words. And interestingly, the use case of our API is the exact opposite of the use case of our site. People do not come to our API to look up words like hagiothecium. They look up… They want to get definitional data, pronunciation data, about normal words. They want traditional dictionary definitions, and they also want, basically, our most popular API which is please give me a random word I don’t really care what word it is.

So, you can look, we have more than 20,000 registered developers. The API serves about eight million calls a day. The bulk of our users make fewer than 2,000 calls a day and about 40 to 80 new developers sign up each week, probably our most marquee customers are DuckDuckGo, the privacy protecting search engine. And, let’s see, and people that make a lot of apps to help you cheat at Scrabble.

So, now, a lot of those 40 to 80 developers who sign up each week are new to coding. So how do I know this? Well, there are lots of .edu addresses and lots of them come in batches all from the same. edu. So perhaps thirty people all from the same college or university sign up in a week, which seems like a traditional class size. We asked for descriptions about what developers are gonna be doing with the Wordnik API , and we get answers like, class assignment or school. And the email that sends you your key is currently borked, so I send out the keys by MailChimp every week. And I get a lot of people anxiously emailing me, I haven’t gotten my key yet, and my assignment is due. That is a pretty significant tell that someone is in school for coding and is trying to learn. And I promise you that keybork will be fixed next month. It’s almost done.

So, we’ve got a lot of new developers. If you also have a lot of new developers to your API or your service, how can you best support them? So I’m assuming that you already are doing the obvious things, you have a welcoming presence across a lot of different Q&A sites on Stack Overflow, IRC, Twitter, Getty maybe even an open slack channel that you’ve scrubbed all your API documentation insight of references to rockstars or ninjas are crushing it. And that, I could also say from experience, that people tend to think that you have a friendlier online presence if your logo has a heart in it. But I understand that that’s not an option that’s available to everyone. Actually, I can tell you a funny story about this like, Wordnik’s original logo did not have a heart. Wordnik’s original logo was appallingly ugly. And when we changed it, obviously, anytime you change something on the internet, people get pissed off. That’s just what they do. Like, that’s how the internet works. But the one criticism that really, like, stood out from all the rest, most of the rest of them were just like, “I don’t like it.” One of them emailed and said, “Your new logo is too girly.” And I was restrained from writing back “Duh, girl.” Anyway, put a heart in your logo makes people think you’re friendly.

But a lot of people, especially new coders and especially coders from underrepresented groups in tech, they don’t necessarily feel comfortable asking technical questions in more public venues, or they might just not enjoy recreational arguing, who knows? But, so in order to help support these new developers, it’s important to have an interface where they can just poke at your API. Because sometimes they don’t wanna answer a question in public, but sometimes, they don’t even know what the question is. One of the things that characterizes new developers is they don’t really know what they don’t know. Poking at something and seeing what happens, will happen if I do this, helps them not only answer their question but it also helps to define the boundaries of their knowledge. And know, being able to just curl your API, is not enough. Actually, I think a really good rule of thumb is if you find yourself asking “Why don’t they just X?” That is the wrong question. Because, obviously, if they knew about X and they enjoyed doing X, they would already do X. So if you’re asking yourself “Why don’t they just?” Think about why not instead of thinking like, “Whoa, they should.”

But so, how many people are familiar with Swagger, the now open API framework? Okay. So Swagger was actually invented at Wordnik. How many people knew that? Nobody ever knows that. Okay, yeah. So Swagger was invented by my technical co-founder Tony Tam, and I think he invented Swagger because he was tired of answering my questions about the API. When I founded Wordnik, I knew just enough Perl to be a danger to myself and others. And I had to use a UNIX system and certificate, and that is a cocktail of terrible knowledge. And yeah, that’s just like the hangover from that particular cocktail, lasts a really long time.

But anyway, Swagger came from Wordnik. And our first… Swagger is now run by the open API initiatives called the Open API Spec. It lets you do all sorts of awesome things, you know, generate client code, automated testing. The new 3.0 spec is, you know, out and that one does everything but make you eggs. But it also lets you make a nice sandbox documentation, and that is totally worth the price of admission. And the price of admission to Swagger is free.

So, with Swagger, you get a sandbox, and you also get an HTTP or HTTPS endpoint that you could show people that with calls that you need to make. But before Swagger was Swagger, and it was just like what Wordnik looks like we omitted the API key from what we showed. I don’t know what we were thinking about. We were thinking like security or everybody knows this, but it turns out that this was a wrong assumption. And since I had been doing all the API support, we realized pretty quickly that we got so many, “Where do I input my API key questions?” That we actually changed the interface to show the full strength including the API key parameter. There’s a lot of implicit invisible knowledge in coding. There’s a lot of information that people who’ve been coding for a while have internalized. The people who are brand new to coding have no clue. And I have the emails to support, to prove it. But the more of this that you can make visible, the better. Make no assumptions.

So, some people will figure things out by poking around and some people will ask questions, but there is a not insignificant number of people who will not poke and who will not ask. What do these people do? These people make a lot of calls to your API that do not work over and over again. Their hope springs eternal. And they just keep making calls, and they don’t work. And so they go away sad and mad often after like just hammering your API into submission. And so one way to find these folks is to look at your logs, right? For instance, looking at calls that return 403s we’ll find people who don’t know what to do with their API key. And then you can email them, and you can help them. Looking at 404s, found me people who are unaware that they needed to URI and code things, right? They were just sending straight weird characters. And then looking at 500 errors, found me a lot of bugs that then I can then email those folks and say, “Hey, sorry. It’s not you, it’s me.”

But in an ideal world, a lot of these problems would make it into an FAQ and examples. And this is definitely on the to-do list for Wordnik. Wordnik has always been resource constrained even when we were a venture back startup. We’re now a non-profit so the resource constraining gets a lot more significant when you’re a non-profit. But I don’t know anybody who has unlimited resources. So one of the great things about having a lot of learners who are coming to your API is that student users often have teachers, which is great, and those teachers are your friends. So, for example, Daniel Shiffman, Daniel Shiffman makes some great videos, and he’s made some wonderful ones that show how to use the Wordnik KPI with processing.

Darius Kazemi, who makes amazing Twitter bots, he’s open sourced a lot of bot code that makes calls to the Wordnik KPI and shows people how to use it. If you’re seeing a lot of students signing up, if you’re seeing a lot of learners maybe from code academies, it’s worthwhile to figure out who are these people who are making the assignments, not just doing the assignments and email them to say, “Hey, can you open source your curriculum? Can you share examples? Are you willing to blog about how you teach people using our API?” And, of course, you know, once you find this people, you should link to them, and you should tweet about them. And the best thing about these friends is they’re often really great coders, and they lead by example.

So, speaking of examples and leading by it, one thing I try to do when doing API support is I try to be as transparent as possible especially when the problem is on our side. It really doesn’t benefit new developers to believe that everybody else’s code is perfect and that they are the only people writing bug spaghetti. The faster new developers learn that everything is buggy, the more confident they get which is kind of ironic. So be honest tell them it’s a bug. Give them some kind of window for when it might be fixed even if that window is two days after never and show them workarounds.

And also don’t be afraid to point them at somebody else’s product that will solve their problem if your product will not do that. For instance, Wordnik has a very limited number of audio pronunciations, and we only have them for English words. But the Forvo API has more than 300 languages that they serve pronunciations for, and you can filter those pronunciations by the speakers, gender, and location. So not just female Spanish pronunciations but female Latin American Spanish pronunciations, which is totally awesome. So recommend other people’s stuff because, I mean, we’ve heard a lot about the jobs to be done framework. Sometimes your product doesn’t just do that job, doesn’t do the job, and you should help people get their jobs done.

Of course, how can you make money especially if you’re sending people to other products, and how do you measure the return on investment of supporting new developers? So I think that the path from learner to paying customer is a very long one, and Wordnik has not tried to monetize our API very seriously as a venture back startup. We’re starting to do that now as a non-profit, but our mission comes first. And our mission to, you know, find and share all the words of English means that while we are trying to monetize the heavy users of our API and add more services, we’re not trying to unicornize. Actually, I was trying to figure out, like, what’s the opposite of unicorn? Like, what’s an animal that’s extremely common and has no market value? And the only thing I could think of was squirrel. Wordnik is a squirrel, we are not a unicorn. So monetization is tricky for new developers, but I think you can get a lot of value in other ways.

So one way to justify the expense of helping newbie devs is to treat it as a way to onboard your own developers, the ones who work with you because you never really know something until you can explain it to somebody else. You can also treat it as product research. New developers show you where the friction is in your product because they don’t have the muscle memory that more experienced developers have. What makes an experienced dev just shrug and work for their normal work around will stop a newbie dev right in their tracks. And also, helping your own developers to help other developers helps build empathy and product awareness in your own staff. If you rotate your staff through doing support, you should see more bug fixes, you should see improved documentation, and you should have less tolerance inside your own organization for the rough patches in your UX because nothing gets things fixed more than having to support a hundred people with the same problem with your product.

And, of course, you might think of alternative ways to monetize maybe you should get into the educational market if you have so many people using your product, maybe you should set up a paid course for devs using your product. Maybe you can license some of your content to educational organizations or aggregators. I feel like the nostalgia cycle is way faster these days like, you know, my teenage son is already nostalgic for Pokemon games he played four years ago. Like, that seems really fast to me. So, you know, these people who are learning today two years from now you should go and try and sell them throwback t-shirts with your product on them.

And also, one of our actual plans, I’m not joking about this is, we are gonna monetize procrastination. If you make a donation, you’ll get your API key right then. Otherwise, you’re gonna have to wait a day or maybe a week. We haven’t decided how desperate people are gonna get yet. But, I mean, that’s the need, that’s the use case that we’re seeing is people are like, “I need that key right now because my assignment is due tomorrow,” all right, all right people cough up the money.” So think about alternative ways to monetize these learning developers if you really have to.

But most importantly, if I had to sum up my philosophy about supporting developers in one sentence, it would be this one: meet people where they are. You know, if you meet people where they are, you can help them get to where you want them to be. If you just stand, you know, far away from them and wave, they have so many opportunities to wander off the path. Go to them and help them where they are. Also, if I have learned anything from reading fairy tales, it is that kindness to people who seem humble never ends badly and that arrogant behavior almost always ends badly.

I like questions more than I like answers, which is probably why I enjoy supporting new developers so much. I’m happy to answer any questions that you might have at the discussion or at the break, or by email, or via Twitter. Also, I really welcome critical feedback. I don’t have a computer science background. I’m a linguist by training that explains all the dictionary stuff. And I really appreciate it when people help me fill in the gaps in my knowledge. So thank you so much for your attention. Here’s some Twitter ways to reach me. Also, I really wanna thank the people of Flickr who openly share their fantastic images, so this whole entire presentation is CC BY-NC ShareAlike license. And so I’m happy to share my slides with you so that you can give a completely different talk using all these same slides in the same order.

So, thank you so much for your kind attention. I really appreciate you all taking the time to listen to me. Thanks again.