Breaking down barriers to 'Hello World'

Transcript

So, the last time I gave this talk, there was a hurricane outside. So, this is already doing, we're already doing better. Yeah, Alice was there. There was very few people there. But yeah, that was a few years ago, so I resurrected it. So let's get started.

So first, I'm going to start with a brief history of the "Hello World" program. This is the first "Hello World" program, it's kind of blurry, but it was written by Brian Kernighan, a Canadian computer scientist that worked at the Bell Laboratories in 1978.

And the reason why he wrote it was because there was no standard first program to be able to figure out whether the compiler and all the different environments were working together. And so he wrote it, and then it became more popular in the late 70s.

And I think that's really cool because it's a program that, like, transcends history. The only thing that's really changed is we lost the comma somewhere along the line, but, like, we've been using this program for decades. And, I don't know, it gives me little warm feels.

Putting software to immediate use

But why is "Hello World" important? A lot of people have been talking about that. I'm not going to reiterate all of everyone else's talks, but what I think is the most important thing is it's putting software to immediate use.

You know, you want to be able to have people use your software, or tooling, or API, or whatever as fast as possible. That creates just a great start to that developer experience, and "Hello World" does that. It gives them those great feels.

And so, we write "Hello World" tutorials to serve our developers the best we can. But there's a lot of other downstream effects that everyone in the sales and marketing team can also get from this. But if I wanted to put "Hello World" into a category of metrics, it's activation, which I would probably argue is one of the more important ones, but that's a whole nother talk.

Time to Hello World

But back in 2012, Adam DuVander, who spoke yesterday, you know, wrote this blog post on ProgrammableWeb about "Six Ways to Accelerate Time to First 'Hello World,'" and it became this metric that we actually started talking about on our teams, like, time to first "Hello World."

And what I also think is it's early wins, wins are empowering, especially when you're not used to something just working. You know, if you've experienced a lot of bad docs, that win, that amount of dopamine, it's a really great feeling, and it helps people go accomplish a lot more after. And this is something both beginners and experienced programmers experience. It's not just beginners that get this.

Beginners have less access

But the reality is beginners have less access. They have obstacles that create this nagging sensation of self-doubt, they have less access to mentors, less idea of what terms they should be Googling, which we know we all do every day, but I also see that these struggles are struggles that beginners face.

The beginner struggles are all of our struggles. And so, that's why I don't really like differentiating this as this is something for beginners. This is for everyone.

So, who am I? As I said earlier, I'm the lead community engineer at Stoplight. Stoplight is a pre-production API design platform, so helping empower developers to create better APIs through better API design using OpenAPI specification, which then leads into instant mock servers, and style guides, and autogenerated documentation, and a little bit of contract testing.

What I do is I'm helping hundreds and hundreds of people use OpenAPI for the first time, and that's with a form visual-based editor. But what I really see is I'm helping people create better API experiences because with a better-designed API, their users are getting a better experience. Before that, I worked at Keen, where I helped to manage SDKs and docs.

That's all

So, I want to first start with a few different barriers that I've regularly seen or even felt myself. So there was this tweet a few years ago from Tracy, and I looked up the doc that she actually tweeted. I'm kind of keeping it nameless, but you don't need to read any of that, but all you need to know is there's some hefty stuff there to get started.

And at the end, it says, "That's all." And, you know, there's some people that made it seem kind of harmless when you first read it out of context. But when you think about certain words like, "that's it," or, "simple steps," or, "straightforward," or, "easy," when you're struggling, those make you really feel not great.

They're really demoralizing. When you're trying to get an API to work, you're, like, carrying these terms. You're, like, questioning your intelligence, "Am I stupid? Why can't I just get this?" And it's just not great feeling.

So, I classify this as oversimplification. It's all over our documentation. And many times this happens because the people who are building the documentation, the initial documentation, are also the people building the tool or the API. They're the one who wrote the code. They're the one who designed it. They're testing it many, many times over, and then they wrote the docs for it.

And so, after you've done something that many times, yeah, something starts feeling easy to you. But what about if you've never seen that UI before, or you've never seen that API documentation? It's not easy.

Types of failure

And so, there's two types of failure this kind of falls into. So empathy failure, "The problems caused by these words don't affect me, so, therefore, they don't exist." Or, beginner's mind failure, which is, "It's perfectly clear to me, and I don't understand how someone cannot, like, understand this." And this happens all the time. We'll talk about some solutions in a little bit.

Wasted energy

Then there's wasted energy. So, deciding what tools to use, or configuration, or dealing with unfamiliar errors. It's a giant pile of parts that people don't know what to do with.

One example of that is just choosing a text editor. A lot of us have our favorite now, so this isn't a thing we think about a lot. But, say, you want to write some JavaScript, so do I use Sublime Text, or Atom, or VS Code?

Maybe I want to write some Java, Eclipse, NetBeans, or IntelliJ. And then maybe Python. Do I want to use a specialized Python IDE, or do I just want to write that in, like, Sublime Text?

Bad docs

And then there's bad docs. So, that probably sounds like all of this could be bad docs, this kind of generalization, but I want to focus on the part that's, that pile of parts that you have no instruction for how to put together. Some of us like Legos, some of us don't. But our docs should not be that way with no intuitive design and no instructions.

The dev environment

And then the last one is the dev environment. So, I want to try out something new, but I don't want to spend a whole day or more updating dependencies on my local environment just to try to get that set up so that I can make an API call that will only take me five minutes. I'm going to give up and go use some other tool because that's what's going to happen.

Or, what if the whole "Getting Started" was written for Unix-based and someone using Windows just like, they just rage quit that?

And so, what do we do? How do we fix these, and not only help beginners but also more experienced developers?

Start with the basics

We start with the basics first. Quick start guides are written to lower the barrier to entry while learning by doing. It's important for the neural connections when you're learning something to actually, like, have that action of doing things.

But the key is not to overcomplicate them, which often happens. Things just start getting piled on and added. You need to focus on how to do the simplest things in the least number of possible steps.

So, say, there's a complex setup requirement. Maybe there's some tooling you could write to help make that easier. Maybe there's features that are complicating things, like, you're having to do these longer explanations. Do those features actually need to be part of that quick start? Maybe they belong in some other kind of documentation.

And then also remember Windows, so you need to support multiple types of operating systems. When we're writing quick start guides, we're trying to do what's best for the developer. And there's a lot of things we often think, like, quick starts are just one part of a lot of documentation we need to write. But if we don't do that right, we're failing them. And, all the other good things that the business cares about will follow after, but you got to get that step right.

So, my experience a few, this was probably about six years ago. The first time I used the Twilio API, I was writing Java. But I hadn't really done a lot of Java on the web, and so I was trying to get my server set up and some other things, and I was just struggling.

But then I saw the older version of this guide, this is the new version, of how to set up a Python and Flask development environment. And I had not written any Python at all at that time, but I was like, "Oh, that's kind of cool. Maybe I should try that out." And I was able to get set up super fast, and I was just like, "Wow." I was so won over that I started writing Python full-time after that.

But what I love about this is it helps, what I talked about, like, choosing an editor, something so basic. This is Step 0 basically. We miss Step 0, but this is what I would consider our Step 0.

Virtual environment, really important for when you're developing in Python, and then also explaining ngrok. Because if you've never, you know, used a lot of APIs, you know, ngrok was a really helpful tool when it first came out, and it still is. But it wasn't something that you just knew about initially.

Then there's the Spring Framework. They have these "Getting Started" guides that are very task based. So, this one is, "Building a RESTful web service."

What I love about this, it's very action. Users don't care about what your content type is. They have a task that they want to do, and they want to do it as fast as possible because they need that for their job, and this one is very much that.

What I love about it is in the Table of Contents, there's a "How to complete this guide" section. And it's geared to not only beginners, but also people who have existing setup or are more experienced. So, if you want to start from scratch, you can do that. If you want to skip the basics, they tell you how to do that too.

And then, for everyone, you can check what you did was actually correct. And then also, like, build steps in Java, especially for anyone. So, maybe if you're new to the Spring Framework, some of those things can be complicated, and they give you help with all that.

Working code

The next one is working code. So a lot of our docs have lots of examples. I would wager that if I were to go copy and paste the code that you told me to copy and paste, and run it, and I'm guessing maybe how to run it if it didn't tell me, a lot of it won't work. And a lot of times, that's because we're missing libraries, or we're missing different things.

A few years ago at Keen, we had done a developer community survey. And we asked people, "What would you like to see more in our docs?" And we already had examples in our docs. But this was the word cloud that came out of that. And it was... So, examples must have been said so many times that my teammates actually thought I was joking, like, I had just, like, fabricated the results, but this was actually what came out of it.

And so, you know, users are really wanting more examples. So when we have these examples, if you saw the talk yesterday, what happens next when I tell someone to go copy and paste this command? Seems pretty harmless, but it's a bash command not found because they were able to copy that dollar sign.

And, to me, I instantly know what I did if I accidentally do that. Like, yeah, the dollar sign. I left it. I copied it. I go and fix it. But to someone who's not experienced, it's really hard.

And have you ever tried to Google that? Like, you know, you're not going to be able to find out, exactly. I mean, maybe somebody had a similar experience with a different tool and then the error, but that's super complicated.

So my suggestion is if you can control the CSS of those docs, make it so that dollar sign is uncopyable. Or, maybe just don't put that dollar sign in there at all and explain where this command was supposed to be run.

A lot of what we're trying to do, though, is people are, like, getting started, but we want people to get it into their production environment. Like, we want them to go deeper into the application. We want them actually putting this into code that they will deploy.

And I love this from Auth0 because they have all these different language-specific guides, and they do that. They have it where you get an option. You can play around with sample app, or you can actually put it into your actual application, and they gear the whole tutorials around that. So, getting it into production, that's what we want.

And then on that same theme, you know, different buttons, like Remix on Glitch, you know, automatically getting that deployed, or maybe you're deploying to Heroku, or Azure, or Bluemix.

Like, find what platforms, maybe there's some common platforms that your users are already on, see if these are an option to be able to have these projects that they can just click to automatically provision and have run on their platform of their choice.

Another example of that is a Docker container. I've been seeing more and more, sometimes users will ask, like, they want a Docker container so that they can run that sample app.

Common error library

The third one is common error library. I think a lot of times we forget that error messages are a form of documentation. And so, say, I get a 401 with the Twilio API, but there's this, like, URL in the More Info section.

So, I go, this is the bigger error library. There's a lot of error codes in here. But specifically, the one that I hit was this 20003 error, and it's got a lot of different things. I only took some snippets of it, but what I say is, like, the money section is the possible solutions.

It's very actionable things that people can go help themselves instead of us needing to help them. And if we write this out, we're multiplying ourselves and how much we can help people.

A lot of times, we don't have troubleshooting sections in our docs or these, like, error message libraries, but I think they could really have a lot of impact. Your support teams would definitely probably love them, different things like that.

More user testing

And then the last one is more user testing. So, more user testing, that sounds pretty obvious, right? Like, we should be talking to our users. But I regularly see people, including engineers on my own team, put docs out there that they maybe only had reviewed by one developer that was very familiar with that project.

And so I say, "Have someone with less familiarity review your work." And I say "less familiar" on purpose. They could be an experienced developer, but just not be as familiar, and they're still a great person to run it by because they are playing that persona of the more advanced developer, which we need to care about too. Put your docs in front of them and have them follow through.

Maybe there was a library on your machine that you didn't include in setup, but it wasn't on their machine. They're going to hit that, and that's a step you need to fix.

But also, what's important is, especially if you're doing this to less experienced developers within your team or community, develop an environment where questions are encouraged, related in, like, the review process, like, the documentation review process.

Because sometimes, to them, it may feel like they want to ask a question, but it feels like a "stupid" question, but it's totally a valid question because that's the question your users are going to have. And so, making it an environment where that's an acceptable thing to bring up.

Pathways to empathy

And what I say that a lot of this user testing, it's a pathway to empathy. So, empathy is the ability to understand and share in feelings of another. But what do we do if we don't know how to feel the pain?

Kat King from Twilio gave a really great talk a couple of years ago at Write the Docs about empathy-driven development, and how this whole journey that they've been on at Twilio to improve their documentation.

And one of the things she said was traffic and signups don't tell you if you're serving your developers well. You need more data to support that.

And we won't always have the same experience as our developers, but we can choose to expose their struggles and connect to the emotions they feel, so we can then have empathy with those emotions. Even though those might be like my experience with a different API, I can connect with, like, "Oh, yeah, that feeling really sucked."

And so when we're empathetic to our users, we're not only empathetic just to beginners. It's everyone.

You should really watch her talk, but one of the things that she did or the team did was they added ratings onto the pages. And if you got less than four stars, it would have a pop-up to prompt with more, asking more questions.

And it was a great way to get data without having to do a lot of, for a smaller team, especially if you don't have resources to do more formal user testing, which I would also definitely recommend if you can get to that place. But this is a way to start getting that data to just try to inform your development of your documentation.

Meeting developers where they are

And so the last thing I want to end on is meeting developers where they are. We need to find ways to do that. So, find ways to feel their pain, whether that be user testing, or, you know, watching them go through the documentation, and then drive change based on those pains.

Because if we cannot drive change, we're basically, like, "I feel useless as a developer relations person." So that's a whole nother topic, but, yeah, think about where to meet them.

And, I'm going to, it's not up yet, but I will post the slides there with some other resources, links, talks, some blog posts, my email, Twitter, and then any OpenAPI-related, or, you know, API design questions, or you want to explore what API mocking, or doing style guides, programmatic style guides, check out Stoplight or let's chat later.

Thank you so much.