WEBVTT 00:00.000 --> 00:12.640 Okay, so welcome everyone, and welcome Emily Omir, we are talk on how to write a killer 00:12.640 --> 00:15.000 read me, please give an applause. 00:15.000 --> 00:27.880 Okay, excellent, thank you so much for coming, before we start, how many of you guys have 00:27.880 --> 00:28.880 ever written a read me? 00:28.880 --> 00:35.720 Okay, and how many of you are convinced that you wrote an awesome read me, the best possible 00:35.720 --> 00:37.440 reading out there? 00:37.440 --> 00:39.880 Whoa, that's like not a huge percentage. 00:39.880 --> 00:45.280 Okay, well hopefully this talk is going to help you write even better read me in the future. 00:45.280 --> 00:48.920 Before I start, just a quick introduction about me. 00:48.920 --> 00:53.320 I am a positioning and product strategy consultant for open source companies. 00:53.320 --> 00:57.840 I also host a podcast called The Business of Open Source, which you should all check out. 00:57.840 --> 01:04.160 I organize a conference for founders and leadership and open source companies called 01:04.160 --> 01:06.360 open source founders summit. 01:06.360 --> 01:11.600 So that's a little bit about me, and now let's talk about readmees. 01:11.600 --> 01:15.000 And I should mention the reason that I'm so interested in readmees is because a lot of 01:15.000 --> 01:20.440 the work that I do on strategy with companies is then translated into a readmee, ideally 01:20.440 --> 01:21.720 at least. 01:21.720 --> 01:26.960 And your readmee is a lot more important than most people tend to think. 01:26.960 --> 01:31.360 So what do you think a readmee is all about? 01:31.360 --> 01:33.200 This is a pop quiz. 01:33.200 --> 01:36.880 So do you think it's about just telling people what steps, what practical steps they need 01:36.880 --> 01:40.080 to do in order to get started with the software? 01:40.080 --> 01:44.240 Do you think it's about helping people understand if your project is going to work for 01:44.240 --> 01:46.840 them or not if it's going to meet their needs? 01:46.840 --> 01:51.640 Is it about helping people go away because your project actually is not going to work 01:51.640 --> 01:52.640 for them? 01:52.640 --> 01:55.680 Is it about making people give you a star? 01:55.680 --> 01:58.880 Is it about showing off all the awesome use cases? 01:58.880 --> 02:00.120 Or is it all of the above? 02:00.120 --> 02:03.400 Okay, what do you guys think? 02:03.400 --> 02:05.600 Yes, it is all of the above. 02:05.600 --> 02:07.400 It is absolutely all of the above. 02:07.400 --> 02:12.160 The problem is that in most cases, readmees do not actually address all of these things. 02:12.160 --> 02:18.000 Usually they stop at that first point how to get started with your software. 02:18.000 --> 02:21.560 But the thing is, a readmee is sort of like a homepage for your project. 02:21.560 --> 02:27.520 Imagine if you go to a home page of a just a random company and all they have is a buy 02:27.520 --> 02:28.520 now button. 02:28.520 --> 02:29.520 That's it. 02:29.520 --> 02:30.800 They don't describe what their product is. 02:30.800 --> 02:33.800 They don't describe why you would want to buy it. 02:33.800 --> 02:36.200 They don't give you really very much information at all. 02:36.200 --> 02:38.800 It's just get started by now. 02:38.800 --> 02:42.440 So that is kind of the equivalent of this. 02:42.440 --> 02:47.480 Would you probably seem before? 02:47.480 --> 02:52.360 So let's talk about what a readmee actually should do. 02:52.360 --> 02:57.360 First of all, this is kind of basic, but it should establish what your project is, 02:57.360 --> 02:59.560 what market category you're playing in. 02:59.560 --> 03:04.480 It should be pretty specific, but somebody should be able to quickly understand exactly 03:04.480 --> 03:06.440 what is your project. 03:06.440 --> 03:11.320 So when we talk about the goal of a home page, it's helping people decide whether or not 03:11.320 --> 03:13.600 they're going to make an investment of time. 03:13.600 --> 03:17.440 In each step, in a home page, you're going to say, am I going to make another investment 03:17.440 --> 03:22.440 of five seconds in figuring out more about this project or about this product? 03:22.440 --> 03:26.600 Am I going to make another investment of 30 seconds, another investment of five minutes? 03:26.600 --> 03:31.320 The thing actually with a readmee is that usually the next step is the getting started 03:31.320 --> 03:34.360 step is more like an investment of 30 minutes. 03:34.360 --> 03:38.320 So you really need to make the case that it's worth it. 03:38.320 --> 03:42.200 You want to communicate the value that someone gets from using your project. 03:42.280 --> 03:46.000 You want to communicate how it's different from the other options. 03:46.000 --> 03:50.600 You want to make it clear that use cases that the project is ideal for. 03:50.600 --> 03:54.520 Also, ideally, the use cases that your project is not ideal for. 03:54.520 --> 03:58.120 So this is a matter of respect for the ecosystem. 03:58.120 --> 04:01.000 Somebody comes to your project, readmee, they look through it. 04:01.000 --> 04:04.760 If it's not going to be a good fit, you don't want them to get started. 04:04.760 --> 04:09.600 You want them to go away and find the project that actually is going to be a good fit. 04:09.600 --> 04:14.240 They will never be a user, but in terms of the health of the entire open source ecosystem, 04:14.240 --> 04:19.720 it is a good thing when people can quickly decide that this project doesn't work for them. 04:19.720 --> 04:27.120 It's really cool if your readmee can also give examples of concrete use cases of how people 04:27.120 --> 04:29.440 are using your project in the wild. 04:29.440 --> 04:34.160 That's a combination of social proof and use cases. 04:34.160 --> 04:37.160 This is what you could accomplish with our project. 04:37.160 --> 04:42.480 Then, obviously, you do want to get to that getting started portion. 04:42.480 --> 04:44.560 But almost nobody messes that up. 04:44.560 --> 04:50.160 So the getting started portion is not the hard part in almost all cases. 04:50.160 --> 04:54.120 Also, I wanted to touch really quickly on the issue of stars. 04:54.120 --> 04:57.920 Giving somebody a star, ultimately, is a bookmarking function. 04:57.920 --> 05:02.000 So generally, people will do it based on the content of a readmee, because they're not 05:02.000 --> 05:04.160 necessarily getting started right away. 05:04.160 --> 05:09.920 If you want stars, have a good readmee. 05:09.920 --> 05:14.400 If you have a company that is associated with your project in some way, it's not the case 05:14.400 --> 05:16.720 for every project, obviously. 05:16.720 --> 05:22.920 The readmee is where you want to make a connection between your company and your project. 05:22.920 --> 05:28.040 The percentage often of users of a project who are even aware that a company exists behind 05:28.040 --> 05:34.040 it is super small, like in the single digits, under 10%, but it's very easy to just put 05:34.040 --> 05:40.160 like a very, very short one sentence line, this project is maintained by X. 05:40.160 --> 05:45.720 If you want to use our commercial product, here's a link. 05:45.720 --> 05:49.840 It's lightweight, but it gives people the information they need. 05:49.840 --> 05:53.040 Tell people that your company exists. 05:53.040 --> 06:00.680 Okay, so I wanted to give a concrete example of a readmee that I actually really like. 06:00.680 --> 06:06.240 This is a project called Argula, it actually was created by a company of the same name 06:06.240 --> 06:08.840 that was in later acquired by HuggingFace. 06:08.840 --> 06:13.720 I will talk about all the things that I like in this readmee, and one thing that I think 06:13.720 --> 06:15.640 that it's kind of missing. 06:15.640 --> 06:19.240 But the first thing is that it has a logo on it. 06:19.240 --> 06:23.880 Again, super basic, you may notice that I am not a design person, because my slides kind 06:23.880 --> 06:30.640 of look like crap, but I appreciate the fact that having a readmee that looks like something 06:30.640 --> 06:35.120 anybody took five minutes to make it look nice, actually does a lot to make the project 06:35.120 --> 06:37.120 look more professional. 06:37.120 --> 06:39.240 So have a logo. 06:39.240 --> 06:44.840 And then you go to this, the first line there that says build high quality data sets 06:44.840 --> 06:51.240 for your AI models, that is the outcome of using their project. 06:51.240 --> 06:54.640 And that's the thing that you really want to start with that you want to put forward, 06:54.640 --> 06:58.400 because somebody is going to come to your projects readmee and say, that's the outcome 06:58.400 --> 07:02.240 that I want now I want to get started. 07:02.240 --> 07:09.800 Then you have a couple of these buttons, that's also good, a little bit of social proof. 07:09.800 --> 07:16.000 Then you have a sentence that's high level positioning, again, super succinct description 07:16.000 --> 07:20.600 of what this project is and who it is for. 07:20.600 --> 07:24.480 The who it is for portion is also really important, because you remember part of the 07:24.480 --> 07:30.000 goal is to help people decide, this is for me, or this is not for me. 07:30.000 --> 07:36.200 Second sentence there, if you want to get started, here's an easy way to do so. 07:36.200 --> 07:39.040 This actually I think is a really smart thing to do. 07:39.040 --> 07:43.280 I know I talked a lot about don't just ask people to get started right away, but you 07:43.280 --> 07:49.320 can give them that option, hey, potential user, you have already decided that you want 07:49.320 --> 07:54.400 to use this project, you don't need all this other information, here's a link, get started 07:54.400 --> 08:00.640 skip all the boring stuff, put that in there, but you still want to have that other 08:00.640 --> 08:04.720 information for everybody else that actually needs it. 08:04.720 --> 08:08.320 Also, they're making the connection with hugging face, which is now the company that 08:08.320 --> 08:12.680 maintains this project. 08:12.680 --> 08:17.480 The next page, I don't know if you're going to have time to read this whole thing, so 08:17.480 --> 08:22.880 you can always go look them up later, but this is why I like this readmee so much, because 08:22.880 --> 08:31.440 it starts with a short but very detailed description of why you should use this project. 08:31.440 --> 08:34.960 One of the things that's really hard about writing these descriptions is figuring out what 08:34.960 --> 08:41.280 is the balance between technical detail and features and talking about outcomes and values. 08:41.280 --> 08:46.080 That's something that's really hard, I'm not going to go into how to get that right, but 08:46.080 --> 08:52.080 be aware that that's hard, you do want to include a pretty detailed information, but 08:52.080 --> 08:55.800 you don't want to just get bogged down in all of a list of features that your project 08:55.800 --> 08:58.200 has. 08:58.200 --> 09:03.240 Then you have these three bullet points, these three subheaders. 09:03.240 --> 09:06.760 Those are what we call differentiated values, these are the things that make our 09:06.760 --> 09:12.840 you look different from every other way that you might try to get better quality data for 09:12.840 --> 09:15.000 your AI models. 09:15.000 --> 09:19.480 So basically, every other way that you might try to get the same outcome, because ultimately 09:19.480 --> 09:28.280 your project is being chosen in comparison with other options, other open source projects 09:28.280 --> 09:34.000 and other commercial options, also sometimes manual processes as well. 09:34.000 --> 09:39.200 You want to address not just in general terms, why someone would want to use your project, 09:39.200 --> 09:44.320 but why someone would want to use your project in comparison to the options that they're 09:44.320 --> 09:47.240 most likely comparing you to in your head. 09:47.240 --> 09:54.920 That is exactly what this read me does with those three bullet points or those three subheaders. 09:54.920 --> 10:04.120 Then we get to the next page, what do people do with RGLA? 10:04.120 --> 10:12.080 This starts to get into that social proof and example use cases. 10:12.160 --> 10:21.000 This is giving some concrete specific case studies of what people have done with this project. 10:21.000 --> 10:25.120 This is really powerful because now as a user, you feel a little bit more confident that 10:25.120 --> 10:31.240 this is a serious project that serious people use it, but you also get an idea of what they 10:31.240 --> 10:32.520 use it for. 10:32.520 --> 10:37.280 So you can see if I want to do exactly that same thing, well, this would be a good project 10:37.280 --> 10:39.720 for me to use. 10:40.640 --> 10:46.040 By the way, I just took screenshots, but if you go to their actual read me, you just scroll down 10:46.040 --> 10:49.040 and you'll see exactly in the same order. 10:49.040 --> 10:51.840 Because then they have another use case section. 10:51.840 --> 10:55.480 So even more social proof, I think that's really cool. 10:55.480 --> 11:02.280 And then the only thing that I actually think is possibly missing here is reasons to not use RGLA. 11:02.280 --> 11:09.160 This goes down to the idea of saving people time, even if they're not going to be your users ever. 11:09.400 --> 11:13.680 Whether or not you need to do this, actually can be project by project because in some 11:13.680 --> 11:15.840 cases, there's not a lot of confusion. 11:15.840 --> 11:21.880 But if you find that you end up getting asked a lot of questions from people who probably 11:21.880 --> 11:28.280 never should have used your project, you can proactively try to help them make a better decision. 11:28.280 --> 11:31.560 And in fact, even include links, do you want to do X? 11:31.560 --> 11:37.240 In that case, here's one, two, three different projects you might want to consider instead 11:37.240 --> 11:41.280 of ours, because ours is not a good fit for that use case. 11:41.280 --> 11:46.800 OK, finally, now we get to the getting started part. 11:46.800 --> 11:51.640 After you have done all of those things, then you help people get started. 11:51.640 --> 11:56.680 Most people don't mess this up, so I'm not going to go into it that much. 11:56.680 --> 12:05.000 OK, so a quick recap, if you want to write a killer read me, you should tell me why I should 12:05.000 --> 12:11.520 dedicate 30 minutes of my life to getting started with your project, because it's probably 12:11.520 --> 12:14.160 going to be at least 30 minutes. 12:14.160 --> 12:19.000 You should do everyone a favor and make it easy for people to understand when they should 12:19.000 --> 12:21.960 not get started. 12:21.960 --> 12:28.520 If you have a company, you should make a connection between your company and your project. 12:28.520 --> 12:32.840 Just one thing to note, if the project is hosted in a foundation, you can't do that. 12:32.840 --> 12:37.320 Sorry, that's one of the challenges if you have a project that's in a foundation. 12:37.320 --> 12:43.400 But if it is not, then the read me is the place where you make that connection. 12:43.400 --> 12:46.440 OK, thank you. 12:46.440 --> 12:58.200 All right, so now everyone can go update their readmees. 12:58.200 --> 13:00.920 If you have questions, do we take questions in two minutes? 13:01.000 --> 13:05.000 OK, we can take a question. 13:05.000 --> 13:12.840 I am a Huskinger, if you have an example for letting people contribute to the project. 13:12.840 --> 13:16.280 Yes, that's actually a really good point. 13:16.280 --> 13:19.960 In the readmees, you should, you mean usually you have computer-grade lines, but you want to have 13:19.960 --> 13:23.960 a link to the contributor guidelines in the readmees. 13:23.960 --> 13:25.320 That's a good point, I missed that. 13:25.320 --> 13:26.320 Thank you. 13:26.960 --> 13:30.960 Sorry, this nice are broken on the link. 13:30.960 --> 13:33.120 The link to the site is broken. 13:33.120 --> 13:35.760 Oh, on the website? 13:37.360 --> 13:40.720 I don't know how to fix that. 13:40.720 --> 13:44.480 I'm sorry that the link to the slides is broken on the website. 13:44.480 --> 13:46.880 I can see if it's fixable later. 13:46.880 --> 13:47.680 Yes? 13:47.680 --> 13:50.320 Do you sit at a readmees like home page? 13:50.320 --> 13:50.960 Yep. 13:50.960 --> 13:56.400 Why is it still in addition to home page also the same information that readmees? 13:56.400 --> 14:00.400 So the question in case you didn't hear is, if a readmees like a home page, why do you need 14:00.400 --> 14:03.760 the same information on your readmees as on the home page? 14:03.760 --> 14:09.120 And the reason is that some people will first discover you through your home page. 14:09.120 --> 14:12.080 But a lot of people will discover you first through your readmees. 14:12.080 --> 14:14.080 They'll discover you through GitHub. 14:14.080 --> 14:20.880 And so you want to have that in the same information in a different format in both places. 14:20.880 --> 14:26.560 Because both places are the front door of your project's shop. 14:26.560 --> 14:29.520 And but you don't know which one it's going to be. 14:29.520 --> 14:30.520 One more. 14:30.520 --> 14:31.520 The last question? 14:31.520 --> 14:32.520 Yes. 14:32.520 --> 14:33.520 Yes? 14:33.520 --> 14:49.040 The question is, how long should be the apt file B and should it contain all of the 14:49.200 --> 14:51.440 information documentation for the project? 14:51.440 --> 14:57.600 Or should we divide it into different marked down files like contributing, getting started? 14:57.600 --> 15:01.600 So the question is, how long should your readmees be and should it be divided into different 15:01.600 --> 15:02.600 files? 15:02.600 --> 15:04.120 I would divide it into different files. 15:04.120 --> 15:08.360 I'd certainly have like a different contributing file. 15:08.360 --> 15:11.720 Sometimes you could even have a different, like a separate getting started file. 15:11.720 --> 15:15.280 That's not your readmees, but that's linked to from your readmees. 15:15.280 --> 15:17.360 You don't want it to be like absolutely massive. 15:17.360 --> 15:21.040 And certainly it's not your whole documentation. 15:21.040 --> 15:22.040 It's the homepage. 15:22.040 --> 15:27.240 Like think of it as the homepage, what how much information do you have on your homepage? 15:27.240 --> 15:28.840 The really essential stuff. 15:28.840 --> 15:31.440 And then you link elsewhere so that people can go deep. 15:31.440 --> 15:32.440 Okay. 15:32.440 --> 15:33.440 Thank you, Edica. 15:33.440 --> 15:34.440 Who was amazing? 15:34.440 --> 15:35.440 So. 15:35.440 --> 15:36.440 Thank you.