How to lose a dev in three ways

I am Jamie Wittenberg, and this is how to lose a dev in three ways. If you like what you hear today or you're just a fan of dank memes, I hope that you'll follow me on Twitter @SteministBarbie. And now, I'm going to tell you a little bit about having better documentation.

First, I'm going to introduce myself and tell you a little bit about my work, then I'll share three ways that your documentation might be causing you to lose new developers. We'll discuss solutions for each of these problems, plus things you can do right away when you get back to your office on Monday. And I will try my best to save some time for questions.

I've been working in curriculum and developer education basically my entire career. These days, I work at Major League Hacking, which is one of the largest in-person global developer communities. Each year we support hundreds of thousands of developers as they learn, build, and share new skills.

I mentioned before that I'm the product manager for MLH Localhost, which is essentially a workshop in a box program to help scale your dev rel initiatives. We create engaging interactive introductions to developer tools and package them as workshops that leaders in our community then go on to teach in their local communities, such as at student hacker clubs and meetups.

We've made workshops in a box for each of the companies that you see here. How many of you are in the audience today are up here? Love it. Okay, cool.

Blockers to successfully trying new products

Having created technical curriculum for a lot of the top developer platforms in the world, I've gotten to try out and adapt a huge variety of documentation. In doing this, I've come across every error message, every bug, every blocker to successfully trying a new product that you could ever imagine.

When we create a new workshop, I actually have dozens of student developers QA them for me and identify all of the ways that they might get stuck when trying out the product.

All of this still did not prepare me for a particularly complex problem that we solved from one of our partners. So, the project had the following requirements. The end product should function as a tutorial to give users a working introduction to Python for AI purposes. Fair. This is what I do. Okay.

Users might not be able to install any software on their machines, users definitely don't have access to credit cards, users should not have to enter their email addresses or any personally identifying information, users should be able to save their work and return to it. This was a nice-to-have.

The budget for this project was not large enough that I could have an engineering team build out a browser-based sandbox, hey, a girl can dream. Some of the users have not written a line of code before, some of them might be using tablets or cell phones for this introduction.

So, I left the scoping meeting thinking... All right. It wasn't actually impossible, and we did find an excellent solution to this problem. I am the third or fourth person today who's going to tell you check out Glitch, it's awesome.

And we actually had to work pretty close with the developer team at Glitch to request some features and work around support to meet all of the requirements from the previous slide.

You're probably thinking to yourself, "I'll never be in a situation that bizarre," and it's true. You probably won't, but each of these points is illustrative of one of the many edge cases that might prevent a developer from ever even getting to try your product.

Inclusive documentation

The good news is, these are mostly things that you can actually prevent by creating inclusive documentation. So, inclusive documentation. You're all at this conference, so you already believe that inclusive documentation is the right thing to do.

However, in this specific case, I want to talk about how the inclusivity of your tutorials and onboarding materials matter, not only because it is the right thing to do, but, in fact, that there is a very strong business case for this, and it's because your documentation is someone's first experience with your product. And so, if your documentation does not enable them to get up and running successfully the first time, you might lose them forever.

And then, finally, at MLH we believe that your marketing materials are, in fact, or your documentation are, in fact, your best marketing materials.

Your docs are marketing materials

How is this the case? Well, there's an apocryphal story that explains the value of this perfectly. In 2011, a team at Intuit realized that they needed to increase their security measures, and so they were looking into adopting something at the time that was a little bit new, two-factor authentication.

And so, there was a product manager and she was going through all sorts of different solutions and comparing documentation and pricing and, for any of you who have done that, this is a nightmare. She came across Twilio, and Twilio had incredible documentation about their two-factor authentication solution.

And this product manager was able to prototype a solution in an afternoon, and she fell so in love with it and was able to get her engineering teams so on board that they adopted it and shipped this solution within a month. Twilio gained a major customer through this experience.

Think about that. A product manager made a prototype without having to involve the engineering team because their documentation was so strong and the company bought that solution. This is the best-case scenario for someone trying your API the first time and you can achieve this through your documentation as well.

Please allow me to tell you how. So, I'm going to tell you three ways that you might lose a new developer based on some things in your documentation, and provide solutions for all of those.

Familiarity with code conventions

So, you might lose a dev because new devs aren't familiar with code conventions. What do I mean by that?

This looks pretty familiar, right? We've all seen this? Does anything here seem out of the ordinary? Nothing, right? This is typical. I borrowed this from a company that I believe has some of the best developer documentation out there, and I use their tutorials and products all the time.

In fact, they have over 2,000 tutorials on their website and I bet you dollars to donuts that they acquire a significant chunk of their user base indirectly by people finding the website because they Googled another problem and ended up there for the tutorial.

So, I ask you, what in this simple command might cause you to lose a new developer? Nailed it. Thank you, Bekah Weigel, for your perfect tweet. To accent my talk, I asked her if I could use it. She's great.

So, for most people, we'll eventually figure this one out, right? But there's so much frustration for new developers simply because the conventions that we've come to know over time are not familiar to them.

And there are a lot of these, for example, using the angle bracket to indicate that you're in an interactive shell, or using braces around values where you want somebody to substitute their API credentials.

Conventions increase accessibility but can be confusing

Most of us use these in our documentation and conventions are good. If done right, conventions actually increase accessibility and inclusivity, but they can be confusing for new developers.

So what do you do about this? I suggest including a legend in your documentation that defines any conventions used. I actually put this together in about five minutes and it is a simple asset that you can reuse throughout your documentation. And this can prevent a new developer from trying one of your tutorials, struggling, and disappearing forever.

You do not want a person's first experience with your product to be one of frustration. They might think that the product is the problem. They might think your documentation is the problem. And that is the worst-case scenario for someone trying your product for the first time.

Okay. Another example, how do you think you might lose a new developer here?

Audience member: They type in fake package.

Jamie: They type in what?

Audience member: Fake package.

Jamie: Oh, they type in fake package. Okay. So pretend this is for a real documentation. Pretend fake package exists. Now, what happens? Yes.

Audience member: They put npm run in their code file.

Jamie: Exactly. So, it's difficult to tell by looking at this, which of these are commands for your shell and which of these are code that should go in a script file. You nailed it. That's awesome.

For a new developer, this might be almost impossible. For somebody familiar with Node development, these things will become familiar to you and you'll be able to do this.

So, I can't tell you the number of times that I've had students testing documentation and they've done exactly this, copied and pasted all of this into their terminal and had no idea why it wasn't working.

Visual differentiation

So, let's take a look at an example of a better way. So, this is, you know, build your first server with Express, build your first route, right? So, we're looking at this code here, there's syntax highlighting, there's number lines, and then when it's time to run the file, it is very obviously different.

This looks like a terminal. So, you should use visual differentiation to indicate different parts of the developer workflow.

All right, third example. What's wrong here?

Audience member: What if you don't have NVM?

Jamie: What?

Audience member: What if you don't have NVM?

Jamie: Okay. So, that is actually a problem that we're going to address in the next section, but, yes. What if you don't have NVM? I'll tell you what to do there too. Okay.

But there's no instructions, on expected output or what to do if you don't get the expected output. You don't know where to enter this, you don't know when.

Removing room for error

So, what can you do about this? I'm going to advocate heavily for screen recording or GIFs of someone following one of your tutorials. It doesn't have to be the entire thing. Even a visual of a few commands or the trickier part of implementing your product or getting up and running can alleviate a lot of stress and confusion for new devs trying to use your product for the first time.

Including the GIF makes it evident that I'm typing these things in my terminal, you can see the output of what I should be getting, and you know that if you're not getting that, that something's not right. You're not going to continue on to the next part of the tutorial and have no idea where you got lost.

There's so much going on when you're writing and running code, right? The nuance of how all of these things work together becomes familiar to us over time, but it can be so hard in the beginning to keep things straight and, frankly, I still mess up. I know that we all do. So, a screencast removes most of the room for error.

All right, let's recap the first way to lose a dev. You might be losing devs by assuming knowledge of conventions and workflows. And you can avoid this problem by adding a legend to your documentation, using visual differentiation between different parts of the workflow, and using screencasts or GIFs.

Oh, my goodness. Some of you are really interested in this. I have like, this is the best day of my life. I'll wait because you're taking pictures. I'll get out of your way. Also, you can actually get this talk online later. I'll give you a URL.

Development environments are hard

All right, so, the second way that you can lose a new developer, development environments are hard. Agree?

Audience members: Yeah.

Jamie: Cool. So, here's an example. This seems fine, right? A simple instruction on how to SSH into a remote server or virtual machine. What's the problem here?

Audience member: Your IP address.

Jamie: Oh, that is one. And I'm not going to give you a good solution for that one. What other problems?

Audience member: How do I open a terminal?

Jamie: How do you open a terminal? Man, you are all really two steps behind me, which is good. That means that I'm not as sharp as you. I love this.

Okay, so this is not actually how this works at all on a Windows box. Unless I'm very much mistaken, you need to use PuTTY or another tool on PC to be able to SSH into a remote server. This assumes that the dev is using a UNIX-based machine.

Assuming an operating system excludes huge chunks of the world

And let me tell you something. So many more people throughout the world use Windows over Mac. Here in the United States might be different. But outside of the United States, it's a safe assumption that a greater proportion of developers are using Windows machines. If your instructions assume what operating system devs are using, you're excluding a huge chunk of the world.

How can you handle this? I liked this one so much. It's got two solutions. So, the first thing is, you can link to someone else's explanation of how to use different operating systems. I borrowed this documentation from Twilio. I know it's the second time I've mentioned them. I swear they're not paying me, but it explains to you that using ngrok is actually very different on a UNIX-based machine versus Windows, and it links out to installation instructions.

But the second part is even better. It actually links to a tutorial that they wrote themselves, which is solution 2B. So, solution 1B. I'm bad at Roman numerals. A slightly more involved solution, but it reaps greater benefits. Why?

Keeping the developer on your platform

It keeps the developer on your platform instead of sending them elsewhere. If you send somebody else to look at other documentation somewhere else, they might get distracted and never come back.

You're also not dependent on someone else keeping their docs up to date. Though you do, the tradeoff is, assume that responsibility yourself, it can bring developers to your platform when they're searching for this particular problem, even if they're not searching for your product.

And finally, it gives them really positive feelings about your product because you care about their experience. All good things.

Okay, so now we've covered accounting for operating systems. Let's explore a situation that's a little bit more nuanced. This one does a few things wrong. It doesn't explain any of the commands you're running, it assumes the commands will work the same across all environments, simply not true, and it doesn't say anything about expected output.

Explain commands and environment differences

So, let's take a look at a beautiful example that I borrowed from some Microsoft Azure documentation. You need to explain commands and environment differences.

So, this tutorial involves using virtual environment to set up a Python environment. And then, activating your Python environment can be different, not only based on operating system as you can see here, but even based on the shell that you're using.

And you could, theoretically, link to the Python or the virtual environment documentation and send them out. But considering there are four different commands that might be the right one to run to get to activate your Python environment, you risk sending someone into a pool of frustration, or you can deliver them from that problem right here.

Not only does this show the commands by environment, but it also shows you what you will experience if you are successful. It says that after running this command, your command line or terminal session should be prefaced with venv. So, now they know what to look for if they did it right. Okay.

A lot of work just to try something

One more example of environment issues. We see this all the time, right? I want to run this tool, and so to run whatever documentation, tutorial, quickstart product, I need Docker, Node 10.0 or later, and Webpack or Gulp, and something about path mumble, mumble, mumble. I'm still not confident that more than 20% of devs even know what a path is.

So, whether you're new to development or just new to this stack, this is a lot of work just to try something. And yes, eventually, installing all of these packages is something that a developer will have to do to use your product, but you don't necessarily want them to end up on your website and go back to do all of this and get distracted, or frustrated, or discouraged. You want them to be successful from the jump.

Providing immediate success

How? Glitch is also not paying me to be here, but you could set up examples on CodePen, Glitch, or repl.it. I know that you've heard a little bit about Glitch today if you've been at some of these talks, but the reason that I love it so much is that you can set up a quickstart, a tutorial, you get the environment all set up for the developer, they don't have to try it, they remix it, and it's ready to go. You have provided immediate success for them.

Now, I recognize that these browser-based IDEs do have some limitations, so I have a solution if there's not a browser-based development environment that works for your product yet. And I recommend, in this case, offering a VPS or VM solution.

So, this is a slide that I borrowed from a tutorial on developing your first blockchain app. Because MLH Localhost is a global developer community, I have users all over the world and I can't know anything about their environment or assume any expertise or familiarity with any of these things.

So, for this workshop, we decided to use a DigitalOean Droplet. That way, we knew that all participants would be using an Ubuntu machine with Docker pre-installed. I wrote a shell script that they could run to set up the rest and then I knew that each person trying this workshop would be successful.

You can simplify the process even more. Different VM providers have different images that you can select, so you can make sure that a developer has exactly the right environment. Bonus points, writing up this tutorial, SEO benefits. Okay.

To recap, you might be losing devs by not accounting for differences in operating systems and environments. And you can solve that by linking to or creating detailed installation instructions for prerequisites by operating system. You can account for different shells when giving commands and explain commands as you go. And you can use a browser-based IDE or describe how to use a VPS or VM to try your product.

New devs lack context

Who is ready for the third problem? Oh my God, I love this crowd. So, the third way that you might lose a new dev is that new devs lack context. What do I mean by this? All right.

So, here's a fictional tutorial that I created of a fairly standard, how to use this API, right? There are a million things that could go wrong here, but I want to focus on the total lack of context at the beginning of this tutorial.

It's easy to assume that if somebody has come to your documentation, that they know what your product does, but that's actually not necessarily true. For example, I don't know what the Localhost API does. I don't know what I have to do to complete this tutorial. I don't know what the expected output is.

Save new developers the headache by adding a few sentences at the beginning of your quickstarts and tutorials to explain what they do. Bonus points for including key activities. Yes, I did borrow this from Twilio. Maybe they should be paying me. All right.

So, example number three. I borrowed this from an API that I've actually used before and I love, and overall, their documentation is fantastic. The problem is that there's so much good information that it can be hard to parse.

So, if you're not actually familiar with using documentation or you didn't come to the docs with a particular project in mind, you might get lost. How can you help tamper those feelings of being overwhelmed?

Provide use cases for your product

Provide use cases for your product and use them to guide developers through your documentation.

Twitter provides this at the very beginning when you first arrive there. What do you want to build? And it directs you based on the problem that you're trying to solve to the different tutorials that they offer. This helps the user get started and then once they get started, they'll be more comfortable searching through the rest of your documentation to build on what they've learned.

This documentation is inspiring. Not only does this help a new user navigate their docs, but it helps them contextualize themselves as a person who uses your product to achieve their goals. This answers a lot of questions they might not even know they had.

Okay. Are you folks ready for my final example?

Audience members: Yes. Woohoo. Come on, now.

Jamie: Oh, I love this. Okay.

So, this is not Google, though everybody seems to think it is when I've been practicing this talk. So, this is blacked out because I didn't want to call anybody out here, but one company that I came across recently does not make it very easy to find their documentation.

I went to developer.hewhoshallnotbenamed.com, and this was the first screen. You could not access the documentation without signing up. I mean, we've discussed this today. Developers don't like to sign up for anything. And this is what I felt like.

If you have an API and someone doesn't know what it does and users cannot peruse the documentation without signing up, they're going to bounce.

Relatedly, a lot of products require you to use a credit card to make an account. I work at a small org, so believe me when I say that I understand budgets and being unable to absorb the cost of every single user who wants to try your product forever without paying for it, but there should be a happy medium between no access and free for everyone.

Create a sandbox

What does that look like? Create a sandbox where developers can try a limited version of your product.

This allows them to feel successful immediately. They don't have to go away from your website, they don't have to set anything up, and it helps anyone who lands on your page understand what your product does, with zero barriers to entry, and allows you to control how much access people have for free. It's a win-win.

Now, I'm very quickly going to show you a slide with five things that you can do Monday back in your office because I am pretty much at time here.

So, to recap, you might be losing devs by not providing context about your product and documentation. Add a few sentences at the beginning of your quickstarts and tutorials, provide use cases for your product, and create a sandbox.

Okay. What can you do...? Oh, sorry. Let me recap. New devs aren't familiar with code conventions, development environments are hard, new devs lack context, and if you don't take these three things into consideration, you will lose new devs. You will lose experienced devs.

Okay, now's the recap I keep talking about. This is what you can do tomorrow. You can have someone with less development experience try one of your tutorials and document every confusing point. You can test your docs on different operating systems, create a legend, add a glossary, and add context to your tutorials.

There's a lot more that I want to say here, but clearly, I have gone over. So, with that, I would love to answer your questions, and you can find this talk at this URL.

Thank you so much for being such a wonderful audience.