Made by
Made by
Cristiano Betta
In this engaging talk from DevXCon San Francisco 2017, Cristiano Betta, a developer experience consultant at Hoopy, highlights the seven deadly sins of developer onboarding. From documentation mistakes and poor navigation to CAPTCHA and not owning your own SDKs, Cristiano vents, entertains and shares some advice.
Cristiano: You have no idea how weird that is to have everybody stand up. Until you stand here, it’s really weird. Hi. I’m Cristiano. Like I said, Cristiano, I’m a DX Designer. I’m trying to get a grip of what time I need to finish this. DX Designer. I work at betta.io or @cbetta. There you can find me, but I’m busy. See, I need to hurry up a little bit because I only have 17 minutes. And I have 17 minutes to be angry.
I’m a Dutch person. In the Netherlands, we’re the happiest people, apparently, according to research. But I have been living in England for 10 years. And with Brexit and everything, I’m just angry, just very angry. And I get angry about very silly things. Anybody from Amazon here? I would really like my Echo to speak up when I talk to it. When you have your Echo at a certain volume and you ask it something and it answers back at that volume and I’m like, “I can’t hear you. Speak up.”
I also get angry about websites. A lot of what I do is just looking at people’s websites and see what they do. And they do really stupid stuff. This is the GitHub Developer site, which, funny enough, since I wrote this talk yesterday they’ve released a new version. There is no link on the entire website from developer.github.com back to github.com, none. To go from developer.github.com to go to github.com, you have to open a new tab and type github.com. It’s really weird.
There’s no signup button, no login button, no, “Hey, you know, here are our API keys.” They’re on the main website. It’s really silly. And it’s silly because I know as an industry we talk a lot about metrics and about money. We spend a lot of money on silly stuff like hackathons, and T-shirts and developer experience. We spend a lot of money on defining what developer experience even is in the first place. We have Phil and his famous AARRR metrics that he’s been working on.
And we do all of that work to make sure that developers are happy and that they are even paying attention to our company in the first place. And then what do we do? We half ass it. We don’t quite get people there all the way. And this talk is called “The Seven Sins of Developer Onboarding”, but really it’s about the deadly sins of developer onboarding. It’s the seven things that I keep seeing every company do over and over and over again.
So I want to apologise. Everybody has been very happy today, very positive. I’m a bit of a cranky person today, not because I’m actually cranky, just because it’s more funny this way. So on that note, number one, and this one is a bit tricky because it has audio with it.
Man: Research has been proceeding to develop a line of automation products that establishes new standards for quality, technological leadership and operating excellence. With customer success as our primary focus, work has been proceeding on the crudely conceived idea of an instrument that would not only provide inverse reactive current for using unilateral phase detractors, but would also be capable of automatically synchronising cardinal grammeters.
Cristiano: That made total sense, right, to everybody? That’s good. It’s not supposed to make any sense, because it is nonsense. Yet, somehow this is supposed to make sense. I like to complain about Amazon a lot. This makes me just think WHAT? I love how every product needs to say either AWS or Amazon in it as well, in case you might have forgotten that you’re dealing with Amazon.
It’s even so absurd that to the point that somebody has actually made a Amazon translation guide on what it is. So S3 should actually be called Amazon Unlimited FTP Server which got me thinking who the hell still knows what an FTP server is? Any millennials in the room? You have no idea, right? PUSHER, anybody familiar with PUSHER? It’s pretty cool WebSockets, stuff like that?
They have a really cool demo where they don’t actually mention what WebSockets, or HTTP or any of this stuff. You just copy that curl command, put it in your terminal and run it and then the colour on the page changes. It’s amazing, but it got me thinking. Who here has curl on their Windows machine? Nobody on the Windows machine has curl pre-installed. Companies that do this well is companies like Twilio. They have a nice little text box on the left where you fill in your phone number, hit send SMS, and you get an SMS. And then they have on the right, they have the code that actually shows how that happened.
But you don’t actually have to write any code to get a workable demo. So that’s number one. I get upset about that. Number two is actually my biggest, biggest problem. It’s this button. Get Started buttons that leads directly all the way to a bucket of nothing, absolutely nothing. Until a while ago, if you signed up for SendGrid and you went all the way through the process of signing up, it then get you to this place where they went, “Thank you.” And I was just like, “What are you interested in at that point?”
PUSHER actually does do a good job there. They just ask you, “Hey, what programming languages do you use?” And then once you give that to them, they tell you, “Oh, here are some codes with the API credentials and everything in it.” That’s good. I can get started with that. There’s this little book called “The Mom Test”. It’s an excellent little book. It’s all about how we ask the wrong questions quite often and we ask the wrong questions to the wrong people. And it’s really just about what do we value?
And when we get people started to the point where we don’t actually get them started but we just get them started to the point that they’re signed up, what are we collecting? Email addresses? Twitter followers? What do we value? Paying users, probably? Quite often getting started doesn’t get somebody to actually pay for your product. Number three, I love this one, is when you type into GitHub documentation mistakes. There’s 43,000 issues of which 8,000 are open. It’s like, “Really?” If you type a typo, it gets even worse.
I tried Ember a while ago. I know it’s not the most popular thing, but they have a really excellent website which the documentation on the side, it has the version number. See. 2.12. And if you go 2.10, they tell you, “Look, you’re on the wrong version. You’re not on the most current version.” Excellent. If you go to 1.13, that’s not there. That doesn’t sound that back, because who’s going to switch to 1.13, right? Nobody, except for if you go to Google and you type in Ember routing, it takes you to the 1.10 release. It’s like, “Just punch me at that point.”
Companies that realise that it’s not just about product. Your product is not just your SDKs and your APIs. It’s your API, your SDKs together with your documentation. If those don’t go hand in hand, you’re not really delivering the full value. You’re just delivering the bit that you care about, the bit that your customer cares about. Companies like GitLab have written very good little pieces about how they ship their code together with their documentation hand in hand and how they make sure it doesn’t get out of sync as they ship it. Stripe does similar things.
Now, I actually have eight issues, not seven. So this is an extra one. I hate the term community. It’s like saying, “Look, we’re all part of the same fraternity here. We’re all cool, right? Let’s hang out bros. We’re already agreed that out product is probably the coolest product ever.” It’s like, “Let’s push community in your face.” I don’t want to join the sales force community. I want to know what the hell they do. We’re all using it. I have no idea what they do. Seriously no idea, it’s shit. Why is it shit? It’s mainly shit because this is often why they push you to community. It’s to push you to the forum so you can figure it out together as to why the code doesn’t work, why the product is broken. That is rubbish.
This is for me. Not for you. Okay, number four. Everybody is familiar with duct tape, right? I have a feeling Anil who was here earlier talking about glitch. Once you have a hammer, everything looks like a nail. And once you have duct tape, everything looks like you can duct tape it. Like the floor. Anybody got kids? That’s a great idea.
Quite often we do things like running documentation unnecessarily because it’s the right thing to do. Because things are broken and we just want to fill in the gap and just… It doesn’t need to be perfect. It just needs to be good enough. And the thing I really get frustrated about with most documentation is their navigation. What am I even looking at here? This is GitHub. There’s navigation here, there. There’s a whole bunch of list here with roman numerals. That’s how you know it’s serious. Collapsible navigation which makes it really hard to search.
Why is it so hard to just stick to three documentation types? Get started, guides and reference. I think in the room if you ask everybody what the difference is between a guide and a tutorial, we’re going to get about 100 different opinions. So just at the top, get started, guides, reference. And then a simple get started guide that actually is comprehensible and in steps. Number five. There’s the marshmallow test. Are you familiar with the marshmallow test?
It’s the idea where you give kids a marshmallow and you walk out of the room. You say, “If we’re back in the room…we’re going to come back in a while. And if you haven’t eaten the marshmallow, you get a second marshmallow.” The great thing is these kids in this video, they’ll touch it. They’ll nibble on it. They’ll smell it, but they won’t eat it. Yet as grownups, we’re extremely bad at this. Here is the get started button again.
When I did a review of SendGrid, you know, where that get started button took you? Yeah, sure. That’s totally getting started. It’s bit of an eager beaver. You’re just getting a bit ahead of yourself. It’s just a little bit too early. Ask me for money once I’ve signed up and I’ve actually used your product. When you sign up with companies like Twilio and Nexmo, they just ask you for your phone number. And then you can start sending text messages and make phone calls to your own phone number but only your phone number preventing spam and giving you a playground to play with.
And then once you add your credit card, that’s when they actually start to give you the full freedom of actually using their full product. Now number six. I don’t get this one. It’s like CAPTCHAs on a signup form. It’s just like, I got all the way there. I agree that I wanted to use your products and you just took me down to that point because…especially the mobile CAPTCHAs can be a pain. I did a review where I looked at SendGrid, PUSHER, Stripe, Twilio at what they use to actually verify that you are a human being. All of them verify your email account. Except for Twilio, they just verify your phone number. It’s a great idea.
You can give people access to an account without necessarily throwing up things like a CAPTCHA, but actually slowly over time verify in a higher, higher certainty that they are not a bot. By having them add a credit card number or something like that, you start to learn that they are probably a real person and you give them more access. Now, number seven and I think there’s definitely some companies in the room that have this problem is when you don’t own your own SDKs.
I used to work at PayPal. When you type PayPal into RubyGems, so that’s the dependencies for Ruby, PayPal is the top one there. The PayPal Gem is not owned by PayPal. The bottom ones are, although that one is a version 0.34. If you keep scrolling there’s a whole bunch of other libraries out there as well, PayPal Permissions, PayPal IPN. And their problems actually originate from their old API where they had a product called Express Checkout. If you type that, there’s actually two Gems both with a 0.03 version number.
Now you might be thinking that’s just PayPal, right? Because if you go to GitHub you’ll find 4,000 repositories of different PayPal libraries that people have written over time. Yet there’s companies like Twitter as well, where if you type Twitter into GitHub, you’ll find 79,000 different libraries. You have no idea which ones of those are good, which ones of those are up to date with the current standards, the current API, which ones have all the features. But even worse is you can’t align those libraries with your documentation.
The Stripe documentation is as good as it is because they write their own SDKs. And they have their SDK samples side by side with their reference documentations. If you don’t own your SDKs, you can’t do that. You can’t give them that developer experience. And of course you can write an open API or a Swagger specification to your community and support your community. Yes, I said the word community. And that time, I did mean it positively.
You can work together with your community in a way that they can actually understand when your changes are happening. Things like having an open roadmap, a very good idea. And then you can have them write the SDKs for you, but I’d still probably advice to just at least own a few of them yourself. Now, the overarching theme across all these seven things is desire. It’s the desire to do things a little bit wrong.
The first one is the desire to be a smart ass, to be cleverer than the other people, cleverer than your customers. You wrote a very good API and a good documentation. It’s better than what the other people have written, than your competition has written. You know it better, therefore your customers don’t… You want to impress them. Number two is the desire to possess email addresses, for some reason, or the desire for other people to just figure it out. You’re being very unfocused.
It’s the desire to be…to ship the documentation before it’s ready or just actually desire to just ship the product before its ready just because you have a deadline. The desire for everybody to learn the same way as you do. That arrogance where you think your product is so marvelous that it’ll explain itself on its own. And then number five the desire to just make money and to make money of everybody even the customers that are probably not ready to give you money yet.
Finally the last two, desire to punish bad behavior, to push the problem of spammers on to your good actors, on the users that you have that do want to use your product. You make them jump through extra 20 hoops just because you have a few spammers somewhere. And finally the desire to have others just make your SDKs for you or the desire to just think that your product probably doesn’t need a SDK at all.
Now, that sounds like a lot of negativity but I want to give it a bit of a positive end here. That’s not my head, I just want to say. There’s this saying which says that you should never attribute to malice, which can be adequately explained by the inability to actually make changes happen. In a lot of companies, there’s all of you working there. There’s all of you people trying to make these changes that I just talked about. And I’m totally aware of that. But I feel like sometimes, as developers, when we use other people’s products, we need to put that in our head as well.
Especially it’s very easy to complain about companies, large companies like Microsoft, PayPal, large established companies and just think them as black boxes of evil. But I know for a fact that there’s some very good people working in most of these companies trying to make big change happen. And often it’s not just malice. It’s really just the inability for them to make changes happen in a large corporation. So that’s me. Thank you for your time. I’m doing a workshop tomorrow. If you will be there, I will see you tomorrow. And in the meantime, we’re going to hand over. Thank you.