Okay, so welcome everyone, and welcome Emily Omir, we are talk on how to write a killer
read me, please give an applause.
Okay, excellent, thank you so much for coming, before we start, how many of you guys have
ever written a read me?
Okay, and how many of you are convinced that you wrote an awesome read me, the best possible
reading out there?
Whoa, that's like not a huge percentage.
Okay, well hopefully this talk is going to help you write even better read me in the future.
Before I start, just a quick introduction about me.
I am a positioning and product strategy consultant for open source companies.
I also host a podcast called The Business of Open Source, which you should all check out.
I organize a conference for founders and leadership and open source companies called
open source founders summit.
So that's a little bit about me, and now let's talk about readmees.
And I should mention the reason that I'm so interested in readmees is because a lot of
the work that I do on strategy with companies is then translated into a readmee, ideally
at least.
And your readmee is a lot more important than most people tend to think.
So what do you think a readmee is all about?
This is a pop quiz.
So do you think it's about just telling people what steps, what practical steps they need
to do in order to get started with the software?
Do you think it's about helping people understand if your project is going to work for
them or not if it's going to meet their needs?
Is it about helping people go away because your project actually is not going to work
for them?
Is it about making people give you a star?
Is it about showing off all the awesome use cases?
Or is it all of the above?
Okay, what do you guys think?
Yes, it is all of the above.
It is absolutely all of the above.
The problem is that in most cases, readmees do not actually address all of these things.
Usually they stop at that first point how to get started with your software.
But the thing is, a readmee is sort of like a homepage for your project.
Imagine if you go to a home page of a just a random company and all they have is a buy
now button.
That's it.
They don't describe what their product is.
They don't describe why you would want to buy it.
They don't give you really very much information at all.
It's just get started by now.
So that is kind of the equivalent of this.
Would you probably seem before?
So let's talk about what a readmee actually should do.
First of all, this is kind of basic, but it should establish what your project is,
what market category you're playing in.
It should be pretty specific, but somebody should be able to quickly understand exactly
what is your project.
So when we talk about the goal of a home page, it's helping people decide whether or not
they're going to make an investment of time.
In each step, in a home page, you're going to say, am I going to make another investment
of five seconds in figuring out more about this project or about this product?
Am I going to make another investment of 30 seconds, another investment of five minutes?
The thing actually with a readmee is that usually the next step is the getting started
step is more like an investment of 30 minutes.
So you really need to make the case that it's worth it.
You want to communicate the value that someone gets from using your project.
You want to communicate how it's different from the other options.
You want to make it clear that use cases that the project is ideal for.
Also, ideally, the use cases that your project is not ideal for.
So this is a matter of respect for the ecosystem.
Somebody comes to your project, readmee, they look through it.
If it's not going to be a good fit, you don't want them to get started.
You want them to go away and find the project that actually is going to be a good fit.
They will never be a user, but in terms of the health of the entire open source ecosystem,
it is a good thing when people can quickly decide that this project doesn't work for them.
It's really cool if your readmee can also give examples of concrete use cases of how people
are using your project in the wild.
That's a combination of social proof and use cases.
This is what you could accomplish with our project.
Then, obviously, you do want to get to that getting started portion.
But almost nobody messes that up.
So the getting started portion is not the hard part in almost all cases.
Also, I wanted to touch really quickly on the issue of stars.
Giving somebody a star, ultimately, is a bookmarking function.
So generally, people will do it based on the content of a readmee, because they're not
necessarily getting started right away.
If you want stars, have a good readmee.
If you have a company that is associated with your project in some way, it's not the case
for every project, obviously.
The readmee is where you want to make a connection between your company and your project.
The percentage often of users of a project who are even aware that a company exists behind
it is super small, like in the single digits, under 10%, but it's very easy to just put
like a very, very short one sentence line, this project is maintained by X.
If you want to use our commercial product, here's a link.
It's lightweight, but it gives people the information they need.
Tell people that your company exists.
Okay, so I wanted to give a concrete example of a readmee that I actually really like.
This is a project called Argula, it actually was created by a company of the same name
that was in later acquired by HuggingFace.
I will talk about all the things that I like in this readmee, and one thing that I think
that it's kind of missing.
But the first thing is that it has a logo on it.
Again, super basic, you may notice that I am not a design person, because my slides kind
of look like crap, but I appreciate the fact that having a readmee that looks like something
anybody took five minutes to make it look nice, actually does a lot to make the project
look more professional.
So have a logo.
And then you go to this, the first line there that says build high quality data sets
for your AI models, that is the outcome of using their project.
And that's the thing that you really want to start with that you want to put forward,
because somebody is going to come to your projects readmee and say, that's the outcome
that I want now I want to get started.
Then you have a couple of these buttons, that's also good, a little bit of social proof.
Then you have a sentence that's high level positioning, again, super succinct description
of what this project is and who it is for.
The who it is for portion is also really important, because you remember part of the
goal is to help people decide, this is for me, or this is not for me.
Second sentence there, if you want to get started, here's an easy way to do so.
This actually I think is a really smart thing to do.
I know I talked a lot about don't just ask people to get started right away, but you
can give them that option, hey, potential user, you have already decided that you want
to use this project, you don't need all this other information, here's a link, get started
skip all the boring stuff, put that in there, but you still want to have that other
information for everybody else that actually needs it.
Also, they're making the connection with hugging face, which is now the company that
maintains this project.
The next page, I don't know if you're going to have time to read this whole thing, so
you can always go look them up later, but this is why I like this readmee so much, because
it starts with a short but very detailed description of why you should use this project.
One of the things that's really hard about writing these descriptions is figuring out what
is the balance between technical detail and features and talking about outcomes and values.
That's something that's really hard, I'm not going to go into how to get that right, but
be aware that that's hard, you do want to include a pretty detailed information, but
you don't want to just get bogged down in all of a list of features that your project
has.
Then you have these three bullet points, these three subheaders.
Those are what we call differentiated values, these are the things that make our
you look different from every other way that you might try to get better quality data for
your AI models.
So basically, every other way that you might try to get the same outcome, because ultimately
your project is being chosen in comparison with other options, other open source projects
and other commercial options, also sometimes manual processes as well.
You want to address not just in general terms, why someone would want to use your project,
but why someone would want to use your project in comparison to the options that they're
most likely comparing you to in your head.
That is exactly what this read me does with those three bullet points or those three subheaders.
Then we get to the next page, what do people do with RGLA?
This starts to get into that social proof and example use cases.
This is giving some concrete specific case studies of what people have done with this project.
This is really powerful because now as a user, you feel a little bit more confident that
this is a serious project that serious people use it, but you also get an idea of what they
use it for.
So you can see if I want to do exactly that same thing, well, this would be a good project
for me to use.
By the way, I just took screenshots, but if you go to their actual read me, you just scroll down
and you'll see exactly in the same order.
Because then they have another use case section.
So even more social proof, I think that's really cool.
And then the only thing that I actually think is possibly missing here is reasons to not use RGLA.
This goes down to the idea of saving people time, even if they're not going to be your users ever.
Whether or not you need to do this, actually can be project by project because in some
cases, there's not a lot of confusion.
But if you find that you end up getting asked a lot of questions from people who probably
never should have used your project, you can proactively try to help them make a better decision.
And in fact, even include links, do you want to do X?
In that case, here's one, two, three different projects you might want to consider instead
of ours, because ours is not a good fit for that use case.
OK, finally, now we get to the getting started part.
After you have done all of those things, then you help people get started.
Most people don't mess this up, so I'm not going to go into it that much.
OK, so a quick recap, if you want to write a killer read me, you should tell me why I should
dedicate 30 minutes of my life to getting started with your project, because it's probably
going to be at least 30 minutes.
You should do everyone a favor and make it easy for people to understand when they should
not get started.
If you have a company, you should make a connection between your company and your project.
Just one thing to note, if the project is hosted in a foundation, you can't do that.
Sorry, that's one of the challenges if you have a project that's in a foundation.
But if it is not, then the read me is the place where you make that connection.
OK, thank you.
All right, so now everyone can go update their readmees.
If you have questions, do we take questions in two minutes?
OK, we can take a question.
I am a Huskinger, if you have an example for letting people contribute to the project.
Yes, that's actually a really good point.
In the readmees, you should, you mean usually you have computer-grade lines, but you want to have
a link to the contributor guidelines in the readmees.
That's a good point, I missed that.
Thank you.
Sorry, this nice are broken on the link.
The link to the site is broken.
Oh, on the website?
I don't know how to fix that.
I'm sorry that the link to the slides is broken on the website.
I can see if it's fixable later.
Yes?
Do you sit at a readmees like home page?
Yep.
Why is it still in addition to home page also the same information that readmees?
So the question in case you didn't hear is, if a readmees like a home page, why do you need
the same information on your readmees as on the home page?
And the reason is that some people will first discover you through your home page.
But a lot of people will discover you first through your readmees.
They'll discover you through GitHub.
And so you want to have that in the same information in a different format in both places.
Because both places are the front door of your project's shop.
And but you don't know which one it's going to be.
One more.
The last question?
Yes.
Yes?
The question is, how long should be the apt file B and should it contain all of the
information documentation for the project?
Or should we divide it into different marked down files like contributing, getting started?
So the question is, how long should your readmees be and should it be divided into different
files?
I would divide it into different files.
I'd certainly have like a different contributing file.
Sometimes you could even have a different, like a separate getting started file.
That's not your readmees, but that's linked to from your readmees.
You don't want it to be like absolutely massive.
And certainly it's not your whole documentation.
It's the homepage.
Like think of it as the homepage, what how much information do you have on your homepage?
The really essential stuff.
And then you link elsewhere so that people can go deep.
Okay.
Thank you, Edica.
Who was amazing?
So.
Thank you.