1. Introduction: Why Readmes Matter
The speaker reflects on how developers focus on the problem their project solves but neglect the readme, introducing the episode's plan to cover bad readmes, their benefits, and how to write a good one.
So, let's take a little bit of time and do some self-reflection here for a second.Think back for just a moment about a project that you've created.If you're like me, or you're like anyone else really, you probably thought about what the tool did.What problem did it solve?So, if you poured all that work into a project and your focus was so heavily on the problem that it solved, then why why would you not spend some time working on the most important file in your projectthat conveys what your program does.And I think you know which one I'm talking about, right?Today, we're talking about the readme.I know, boring.Nobody wants to talk about readmes, but the truth is is that they're probably the most important thing in your entire project.If you don't write a good readme, then no one's going to find your stuff.
It's essentially the gateway drug to your project.So, today I'm going to break down the things that you can do to write a good readme.We'll talk about bad readmmes.We'll talk about the benefits that they bring.And finally, we'll talk about how to write a good one.So, let's go ahead and get into it.
2. Examples of Bad Readmes
A humorous rundown of common readme failures: the one-liner, the ghost, the overexplainer, the out-of-date readme, and the broken promise.
So, before we talk about Good ReadadMes, I think it's important that we probably talk about a few bad ones, right?There's the oneliner.You know what this one looks like?It's the one that doesn't have anything except for the title.Yeah, the ghost.There is no read me.Oh my goodness.There's no read me at all.What is the point?The overexplainer.You know, the one that's like 27 pages long and you tried to read the whole thing, but you're like, "No, I I I can't I couldn't I can't possibly get through this whole thing.It doesn't even make any sense."The outofdate read me.I love this one.And it's the one that talks about how great a project was when it was first built and then the whole thing changed and got refactored.So the readme doesn't even match up anymore with how it works and it just leaves you more confused.
It misleads people.And then finally the broken promise.Everyone loves this one, right?The one that says read me coming soon.Super.That's exactly the thing I was looking for when I was trying to solve my problem.So I think we've all seen the bad ones or we've even done the bad ones.I know I have.
3. Benefits of Writing a Good Readme
Covers the key benefits of a good readme: SEO value, gaining users and contributors, reminding yourself later, and reducing duplicate reported issues.
But you know what's what's the real benefit of making a good readme?because there certainly are some amazing benefits.First off, if you're making an open-source program and you're making this a public repo, probably the number one benefit of writing a good readme is SEO value.No one's going to find your project if you don't write in English what your project does.Just like a blog post or any other kind of article, if you can write in your readme a descriptive title and a descriptive paragraph about what your project does with some good keywords in it, that's what's going tohelp people find your project when they're just searching in the old Googly box.Handinhand with SEO is of course gaining users.Obviously, if people are finding your project, they're going to use your project.And what's the point of even making it if you don't want other people to use it?
The third one is gaining contributors.So, if you if you write a program, you're obviously not going to be able to upkeep it forever.I I think that this is probably one of the hardest parts about open source software design is that you create something and it's a passion of yours and you build it and you put a ton of work intoit, but if you actually do gain a following, you get a whole bunch of people that are interested in your project, then really what you need is you need other people to help you.The next one, and this may be my favorite, is reminding yourself later.Uh, I don't know how many times I've written something and then come back later and be like, "Oh, I know I did that before, but how did I do it?"Uh, the readme is a great spot for that.
Think of it as like a little helpful note to yourself.Last, but certainly not least, the final benefit of writing a good readme is reducing reported issues.Uh, no one no one I don't know anyone that likes to hear about a problem that's in their code that they already know about.I mean, if there's anything that drives me crazy, it's someone explaining to me a problem that I already know exists.So, fix that problem, right?So, put it in the read me.Hey, I already know this is a problem.I'm going to work on it later.Problem solved.All right.
4. The Eight-Part Readme Outline
A step-by-step breakdown of the ideal readme structure: title and subtitle, intro paragraph, diagram or video, user and contributor installation instructions, contributor expectations, known issues, and a donation link.
So, now finally, what you actually came here for.How do you write a good readme?I personally think that it's a it's a pretty simple eightpiece outline that you can put together for any good readme.And I'm going to go ahead and break them down now piece by piece.The first one is a strong H1 and H2 title and subtitle tag.Just start those right at the top.You probably just want to have the name of your project and a very short oneliner about what it does.Second, you're going to go ahead and put in an intro paragraph.The intro paragraph is a little deeper dive.This is where you can really get some SEO value.So, try to build keywords in about what it is that you want people searching for when they find your product.It is going to be the best place for you to not just one explain what the project does, but two embed some words that people are searching for so they can find the product that solves their problem.
Number three, this is where you can get a little more technical.Um, and I think what you'll find is the deeper we go down this list, the more technical they become.But number three is about a diagram or a video or something that just explains a little bit better.If you can make a really good diagram, this is an excellent spot to put it in the third spot in the readme.It'll give you the user a little more explanation, a visual of how your project works.Or hey, if you got a YouTube video with like a with like a demo of how it works, that's even better.All right, so next parts four and five I'm going to go over together because they're essentially the same but for different audiences.Number four is installation instructions for the user.When I say for the user, I mean someone that's maybe even not a coder.
If you've made a project that is for end users to download and install and use, this is where you probably want to put the instructions, right?It might be as simple as you install this with Homebrew or you install this with the following command and then run the following commands to use the tool or double click on it and open it and use thetool that way, right?It all depends on how your project's built, but this is where you need to put instructions for the end user so they can know how to use your project.The next set of installation instructions is more geared towards the contributor.Right?If you want to write code and you want people to help you with the code, then what you should be doing is giving instructions that explain how to build and install the application locally, but also how to work
on it.This these instructions are usually different than the ones that you would give to an end user that just want to use the tool.This is more about people that want to contribute to the tool.So it might include things like downloading the source, compiling from source, uh using a make file, things like that.But I think you get the point.You want to give good clear instructions to a contributor on how they would work on the application and write code and then see it work on their machine before they submit a pull request or something like that.And related directly to contributors, the next spot number six in your outline should be expectations for contributors.I think that if you write something that takes off well, you're going to find people that want to help you.And those people may not know exactly what you're expecting.
This is a good time to tell them.You can say, "Hey, uh, make sure that when you submit a pull request, you squash all your merges."Or, "Make sure that before you pull you submit a pull request, you file an issue first that this resolves."Or before you open a pull request, fill out my pull request uh template.There's a number of different ways you can do this, especially with the features that GitHub offers, but it's going to go a long way in the end with making sure that things are efficient and people are contributing codein a meaningful way.Number seven, I talked about a little bit earlier, but this is this is the spot where it goes.Here's where you put the known issues.Just a simple list.Here's the things I already know that don't work in this program, or here's a list of things I know that were going to work in the future.
And then that way, you don't get a bunch of issues for things that you already know about.And finally, uh, what the heck?If you want to make some money, maybe put a link in there for where people can donate.Um, I know a lot of times donations of money don't exactly help in the open source world.What you really need is time and people, but a few dollars don't hurt.So maybe add a link to buy me a coffee or something like that.And uh, hey, maybe you'll get lucky and make a few bucks.
5. Recap and Closing Thoughts
The speaker recaps the eight-part readme outline, noting it's concise, effective, and helps projects succeed, before signing off.
All right, so there's my list for how to make an effective readme.Again, let's run through the outline.It's an intro.It's an about paragraph.It's a diagram.It's installation instructions for users.It's installation instructions for contributors.It's contributor expectations.It's known issues.And then beg for money.I think that's all you need to have.It works great.It's not too long.It gets the point across and it will help.Thanks for stopping by.