Why most quick start guides flop and how to write a great one

Amit: I'm super excited to be here. This is my first DevRelCon. I'm super pumped, so my name is Amit. So before we start, the title of this talk was not this, when I submitted it, it was something along the lines of how, why quick start guides suck and how you can write a great one. But as I started working on this talk, I realised that I can give you some actionable stuff that you can use to convert those guides into something that doctors would have. So I was like, this is how I want to tackle this. So at the end of this, you will have six quick start guide fixes that you, you'll take home. But before we get to that, we need to talk about quick start guys. In general, those things that are supposed to make us feel like these friendly neighbourhoods, Spider-Man sort of feeling about APIs and SDKs.

And you can go in and it can rescue you. You're super excited about something and they can get you started quickly, but they often turn out to not be that they turn out with this guy who is trying to be super helpful. He just woke up from his sleep and he's super excited about a movie plot that he wants to explain to you, but every word that's coming out of his head is just confusing you even more. So I want you to picture something, it's like stupid o'clock in the morning and you are finally getting, you've been hearing more X or Twitter about this new API and you're like, you know what? Today 5:00 AM is the day I'm going to do this. You already five cups of coffee loaded in and you're like, I'm going to try this out. And you go open up the quick start guide and goes something like this.

The bridge is that guy just woke up, he's like, I'm going to help and this is really not very helpful and I'm trying to hack something super quick. So again, this supposed to, the promise is that quick start guides are this magic genius button that can get you from zero to one quickly, but they are really turning out to be instructions with someone who really hates you. And to be fair, I've been on both sides. I have been on both sides. I have created some guides that question my chick career choice, my existence on the planet, but I've also consumed a lot of them that have really forced me to pull my hair out. So through all of this time, I've spent at Amazon Alexa writing a bunch of these redo writing tech tutorials, but also as a consumer I love hacking on things. So I've also consumed a lot of these guides.

So I've tried to distil them down into six principles, if you may, that I've found that if these guides include those, they make life a lot easier for developers. So without further ado, I present to you there's six different types of guides I've found. So here's a foggy compass guide. There's like a Christopher Columbus sort example where what happens is you get something like this, you get on the quick start guide and it says, welcome to Super API follow the steps below to get started. Now either surface it's like, oh, you know what? It's straightforward. It tells me the steps I can use to get started, but I have no idea what this guide does. It's not clear what I'm going to do, what I'm going to accomplish at the end of this. So contrast that with something like this in the next 10 minutes, your use of API to build a mini app that takes you dad jokes every morning, get ready to be the funniest person at breakfast.

Now it's very clear what I'm going to do with this. It tells me how much time I'm actually investing in this and what I'm going to get out of this. So it needs to be a clear objective and scope. So welcome to API follow the steps, get started is not so good, but in the next five minutes we'll send your first API call that is super appealing to me. I know in five minutes I'll get something that's functional and I can decide if I want to invest further time into this or not. So the principle number one is clear, objective and scope. The second one is what I call the kitchen sink guide. Now this is, I'm sure we've all seen these. It tries to tell you everything that the API or SDK can do. It overruns you with technical jargon. It assumes that you know a lot of this technical jargon and it tries to cover everything in one goal.

Now an example of this would be something like this. It's a shop easy API, and you can create a commerce page, but you can also integrate with chat pause, recommendation engines, and even dynamic pricing. In this guide, we'll touch upon all these aspects and these are the super long guides that just go on until the cows come home. And what I really want is I want them to be broken down into separate guides. So a good example would be in this guide we'll walk you through creating a straightforward product page. We'll cover just the images and descriptions if you're looking to dive into more stuff, we have separate guides for those. So this approach actually does two things. One, it doesn't overwhelm the developer, but it also gives you the opportunity for them to go and explore other things that they might be more interested in. So one guide, one objective, and I try to think of it like a good clean code function. A function should do just one thing. Similarly, a quick start guide should do just one thing.

The next one is the dry toast guide. And I like this analogy because it really how it makes me feel because it doesn't give me any context, it just launches into the guide. So in this guide, for example, super API can transcribe audio. Alright, that's nice. What do I do with that? It doesn't excite me, it doesn't give me any use cases. But imagine if something like this, imagine automatically converting your podcast episodes into searchable blog posts with our transcription Super API. Now you've already started my pre sales going, so give me some examples. And this is also good from a sales and marketing point of view because you're pointing developers to the kind of things that are really good use cases of your API. So there's an opportunity to inspire the developers with contextual use cases. So we should absolutely use that to excite them.

Next one is the puzzle piece guide. This is like it happens a lot. The quick start guide will do everything right until it gets to the code part and they're like, so just paste this code into your project. Where exactly am I pasting this? There's a lot of assumptions the guide is making. It assumes that I know the project structure, it's assuming that I know where the function code goes. So this is something I see a lot. Add this code to your Python project. I have no idea what to do with that. Something like this would be super helpful. The function should ideally go in your utilities JS file under the helper functions. So make it very clear if you can give line numbers if you're going through a progressive thing, give them line numbers where the code goes and if there's also, there's a project structure that they need to understand. It is a rails app and it's going to have an MVC architecture. If you're not familiar with it, here's how it works. Give them some context for the structure that you have.

So clarify code placement and fund structure. And the next one is the treasure hunt guide. This is, again, I've seen this happen a lot, is that you do not provide all the assets or resources that the guide actually needs. So imagine that you have something like test using an audio clip. I have no idea where I can get that audio clip, so I'm already bailing out at this point. Also, if there's a specific use case that the audio clip should be doing, you have lost the opportunity. I'm going to go find an audio clip that's all my desktop, but it may not be the best case for the audio transcription API that you're trying to sell. So to make things similar, here's a sample audio clip, audio clip that you can use for your initial tests. So include the guide. And it doesn't need to be everything doesn't need to be on that guide page, but at least it needs to point people in the right direction of where you can get that. So there should be no missing pieces. You should include all the necessary assets in your guide itself.

And then finally we have the deep end guide. This assumes high level of prior knowledge about your API or the stack. It lacks basic empathy for developers and it provides absolutely minimal guidance. You can do it, you'll figure this out. I'm sure you'll figure this out. A good example of this is something like this. Before using an API make sure you have an API key for instructions. I want to get one, please refer to separate API documentation. Now on the surface this seems very reasonable. This is how probably 80% of the guides are, but it's the other 20%. And I think assembly DI does this really well is that they give you a temporary API key. Now granted your product should be able to support that, but if you look at it from a developer point of view, start from what the developer's doing. This is a great example of getting someone started. You've already given them the API key and if I'm enjoying it, I can come back and I can extend that even. In fact, I think there's not even an account that I need to open to start with assembly.

So the lesson here is that you should remove all the hurdles essentially between to get developers started. So just to recap, you should have clear, objective and scope. It should be very clear what I'm going to accomplish with this study. One guide should be one objective. They should not be trying to do too many things. You should provide contextual use cases that you get developers excited about it. And then you should clarify the code placement and the file structure for your guides. You should include all the necessary assets via demo data, stats, audio clips, whatever. And then finally, you should remove all the hurdles from your quick start guides.

This I think is the ultimate goal. You want to make it so easy that they cannot not try it. That should be the ultimate aim to make your guides create that Netflix sort of feeling of like, oh, you know what? Just one more. They want to hit that part and they should be excited. They should be excited to dive in to your quick start guide. Now I want to give you an example of something that I've been trying out. So I've been writing technical guide for a while now and I found that I was searching for that hello word sort of examples all the time. Even though I was going to, if I'm playing around with Twilio, SMS API or if I'm playing around with SMP as audio API, I found that I was using the same snippets of code over and over again. And going to these photos sometimes is really fighting yourself fighting through the maze of docs that you have.

So I started documenting some of that stuff for my own usage on a page that's really powered by Minify at this point, which is a document writing software. But I found that and I started sharing this with a few friends and I found that this was really helpful only because it was trying to do just one thing. It was a hello word experience of if I was to go and write these hello word pages for all of these APIs, this is how I would've done it. So this is an example for me mostly to emulate if I was going here or give you a quick demo of this.

So if I was writing the first Twilio S-M-S-A-P-I, for example, this is how I would do it. I would get to the code first. Here it is, this one, nothing broken. Lemme show you a re. Yeah, this is if I was trying to send an email using recent API, the thing I really care about, stop mirror. Oh sorry, thank you. So I have a bunch of these examples here, but to drive the point home, if I was writing this hello word writing an email, this is how I would do it. The developers want to know the code. I would give them the code. I'm also doing some best developer practises of giving them this is the way you should be loading your dot and file. All your variables should be there. And then all I do now is I copy this code, bring it into my VS code and I'm ready to go. Is there anything that I need to know from just the hero world experience? It's on this page. So this is the kind of thing that I feel all guides should do. Now this is of course just a hero world example. You could have more complicated examples, but they should follow the same pattern of they just want to do it because it's so easy and simple and basic for that example.

Alright,

And this is the final question that I often ask myself is that would I be excited if I was reading this? Now generally you would get the right answer if you are putting yourself in those shoes and really try to follow the guide, and I've done this myself. You're in time pressure and you just write the guide and you list it yourself. That is really the basic stuff that we often miss out. Follow that guide yourself and see how that makes you feel. If it's complicated for you, it probably is going to be more complicated for other people because you're already in the weeds and if you don't get excited about it, other people will not get excited about it either. So I want to leave you with that. I also want to say that I Kal, who's in the audience here, Kal and I go back a long way, 10 years and we have, after spending about 10 years in corporate, we have started our own thing and that's o dx. And what we do at Hello Dx is we do developer experience audits for companies. So we look at all of this onboarding experience and how we can help improve the developer experience and help you improve the way developers interact with your API. So if you want to take advantage of that, please take a picture of this or QR or whatever and we would love to chat with you and help you through some of this stuff. Again, my name is Amit. I think I'm doing okay on time.

Yeah, lemme have questions. Questions.

MC: I am going to run the mic back. It's a little better for hearing and accessibility. So we'll circle the mic around the room.

Audience member 1:

Thanks Amit. I think I probably made all six of those mistakes. So let's just assume that I have all six of those out there. How do I figure out which of those to solve first? Which one will make the most impact?

Amit: That's a really good question. I think this might be a little subjective for different companies, but for me, if I'm not even getting to a point that I can explore the rest of your guide, the introduction I think is the most important thing. You need to get people excited about the guide. You literally have maybe five seconds. So that introduction should really set the part for what you are going to expect, what you will get out of this. And this happens a lot. I've done this so many times, it's so easy because you just want to get to the meat of it. And as developers, we don't really want to write a lot of this introduction stuff. We just want to get to just the code stuff. So that's what I would do.

Audience member 2:

You talked about removing hurdles, but things like test API keys are a pretty heavy lift for some product teams. So as technical writers we might not always have control over that. What are some other examples of removing hurdles or things that we might have more control over for things like that?

Amit: I mean, so just to talk about the API stuff. Yeah, I completely agree not a lot of companies would have that, but even if that's not an automated thing, you cannot give a 24 hour API key. You can at least point them to the process of getting that API key quickly. One, they should not be in weight. Let's remove this two week barrier that a lot of companies have. Just give a free plan so I never have to come back and talk to a sales person. Please don't send random emails about like, hey, just following up, if I'm key on it, I'm going to come back to it. But also the other thing I talked about from the give them everything they need for the guide, I have played around with APIs where I'm literally only because I'm excited about the API, I've gone in and found the assets or built assets on my own. If you want me to use some images, give me the exact images resolutions that I need, I'm not going to make any images. There's things like that. A lot of this comes down to have you really followed the guide on your own?

Audience member 3:

Hi. I've been different companies where they get feedback from the users on the guides in a lot of different ways. And so outside of hiring you, that's number one. Can you talk a little bit about the approach you take to bringing in the users into Ruby review process and constantly improving on the guides?

Amit: So one of the things that we used to do at Amazon when I was on the Alexa team was that we would have these regular quarterly meetings where we would bring in our champions into the office or just even do this virtually. We would try to understand what are the use cases they're trying to solve for and if the guides or the assets that we have are actually serving that purpose. We found a lot of times we found that the product blogs that we were writing were written from a very product marketing speak point of view. They were not really catering to the kind of things that developers actually doing on the ground. So having those kinds of meetings definitely helps. It can drive the kind of content you want to do. And also if you have five getting started guides and still not solving the problem, there's something wrong in that. Also, you can also do some sort of feedback on the guides themselves because at the end of the day you should also have some metrics that you are using to drive the guides that are actually working on, not if you have a good getting started guide but your adoption rates are still pretty low or you're seeing drop offs on those pages, that's a good indication that something needs to change.

Audience member 4:

Thank you. This is a great talk, lots of insightful information. Thank you so much. And I also follow you immediately. Sounds like a good guide. Follow folks. Also don't hesitate to follow the question about piggybacking on the hurdles and stuff like that. What's your take on automate or not automate certain steps? Because guides can be even for simple things, if you are running some of the complex projects, distributed databases or whatnot, you might be end up in a situation where the guide can't be quite long even though it's like a hell war. What's your take advice on automated certain steps? Kind of like, okay, so there's some bullet plate you need to run the multiple nodes in dock post blah blah blah. Versus telling them you need to do them themselves and make them go through the way I'm personally against the way, so I'm trying to automate as much as I can, but where I should stop automating things and let them go through for things so they can get defensive.

Amit: Yeah, thank you. Thank you. That's a good question. So I want to share an example of a company called LaunchDarkly which does feature flagging. I don't know if anyone's here from LaunchDarkly, but Kal and I were just playing around with that recently and they have an interesting approach where you first sign up and they give you this sort of a walkthrough sort of thing. So I'm not touching code, I'm not doing any of that. But even that quick walkthrough walks you through a CLI command line sort of experience. They give you an API key and then you go do some stuff on the CLI and you make that first API call. So there's not a longish guide, but if you were to write a guide on that, that would probably be a longish process for them. So they give you a taste of that and then they start to get you into that.

Okay, so if you wanted to do this using Python from scratch, then they have other ways of doing this which gets you into that guide experience. So I'm not saying that you absolutely need to simplify everything down into a quick start guide, but the general premise is still that you should make it something that people want to follow and they get excited by that just hitting the next, okay, I get this, what's next sort of thing. So it could be even a video guide that you have, but the point is that when the people start really getting into building something, do you have a guide or sort of a template? Boiler plates are fine. I don't think there's anything wrong with the boiler plates as long as you're setting S for what the boiler plate can and cannot do.

Audience member 4:

Boiler plate scaffolding kind of

Amit: Generation. Absolutely. I think those are great ways of doing it as long as you just set the expectations that this is what the boiler plate can do and this is a good start. Rails is a great example of that boiler plate scaffolding already set up, but you know what the limitations are and you know what you can and cannot do. So that's totally fine. Yeah,

Audience member 5:

Totally writing on the last comment. Great talk. Alright, great talk. Very, very useful. And I think it would be great to learn a lot more from the basic how to page you have or the collection of the guides. My question is around very similarly compared to databases maybe in the AI ML space, what a lot of companies do is they'll actually give you a Python notebook and send you to CoLab and expect you to run the whole thing on a free CoLab account where there's definitely a lot of lift around doing something heavy. Maybe it's fine tuning was the last one that you saw. How do you account for things like that where there's definitely, it's not just an API key you might need, you might have some compute resources involved. Something where it's a bit more of a lift and that's I guess where the vast majority of the content I'm kind of familiar with. So I'm trying to think about how it in that perspective.

Amit: Yeah. Are you doing a lot of documentation on the Jupyter and workbooks themselves or sort of that environment? Yeah, we have ways to do that year. Okay. So I've seen some of that also happen. I've seen people getting pointed to GitHub repos and directly just copy the code from there or go to the school lab and all of that. What I find often is that there's no cohesive step-by-step process for that even it's very ad hoc. It's as if one engineer got on board and was like, I'm just going to do this and this is where we are going to point start pointing people to. So there's no strategy around it and oftentimes I would just get abandoned. Nobody's maintaining that. So as long as there is a strategy for that and you are maintaining it, I'm okay with the comment, the guide being a commented sort of collab thing as long as there is, you're backing it up over a longer period of time. That's fine.

Audience member 5:

More questions anyone? Yeah, my questions around what your opinions are on guides that sort of build on previous guides versus a series versus just having them all be standalone, what your thoughts are there?

Amit: I've done both. I generally enjoy, this is a personal opinion. I generally enjoy going from zero to one sort of things which are not piggybacking on anything else, but there are absolute use cases where you want to educate developers on a certain track, like an educated course of sorts. That's in the last one we built this. So this one we're going to add onto to that. So taking Twilio example, this is the SMS example and this one we're going to build a voice call on top of that. Again, as long as they are, it is very clear that you have, these are the prereqs for that. And here's the other guide, you should follow this one or you can also follow this one completely, which is the approach I like. I want to see that this is a guide all in inclusive that will let me make that phone call.

So I don't like dependency on another guy that I have to go to another guide and get the code from that one first just to get this one that I'm more excited about. So I like it to be contained because the purpose of the quickstar guide is not to give you production code. The purpose is to educate you and then get you excited about the thing that you want to build. So I don't want to handhold completely that you can build this entire this model in this one simple guide. But I'm okay with them getting connected, but they should also be contained that I can use them individually also.

MC: Great. Anything else we have time for? Maybe one more? Yep. Yeah, so building on that last question, the quick start guide, what audience should this be written to? Beginner and intermediate expert. Because you want beginners to feel like there's information for them, but you don't want to board the people. I already know all that. I already know all that. This is a quick start diet and quick start diet. I'm already bored.

Amit: Yeah, I mean even if I say that it should be for beginners and it should be advanced, it's going to pay so much, it's going to be all relative. For someone Python, maybe a new thing for someone. Like a really very advanced topic could be like, oh I know this MS stuff. Why are you getting in a one-on-one with me? So it's about you have to know a little bit about the audience, what kind of audience you are trying to reach out to, but don't make assumptions about, oh everyone would know this. I think we all have the curse of knowledge was my second question. We have the curse of knowledge. We assume that what we know everybody else knows. So one of them is just to be very of that, which is not to be our own trumpet, but this is where having a fresh pair of eyes look at your stuff can really help. Because we don't have any biases. We don't have any political leanings that companies often have internally. So having some fresh pair of eyes definitely helps, but just being aware that question it, that two people know about this buzzword that I'm throwing in here.

MC: Thank you. Alright, well thank you all for your questions.