How To Write a USEFUL README On Github

Let’s be honest for a minute, all of your READMEs are afterthoughts. They are a chore that needs to be done. Well, today IS the day that you could turn all of that around. Today you could choose to give your READMEs all of the respect that they deserve! Come with me on a journey into your README dumpster fire. What it is now, what it could be, and what it could mean for you and your project when done CORRECTLY.

A brief history of bad READMEs
Before we dive into why you want a good README and how to make one, let’s take a look at some of the most notoriously bad READMEs out there in the wastelands of forgotten projects.

Benefits of a well-written README
A well-written README has the potential to be so much more than just another piece of documentation. Let’s take a moment to consider the massive benefits of a README written with purpose.

How to craft a useful, well-written README
Now that you’ve seen the failures and you know all the benefits, are you ready to learn, exactly, how to structure a README masterpiece? Let’s (finally) get into the details. Here’s the list, in order, of elements you should have in your README.

A strong H1 title and an H2 subtitle - Just like writing an article or a blog post, you need a great title and subtitle to attract search engines and humans. It doesn’t need to be the name of your project, but it does help if your title includes the name of the project.

An intro paragraph focused on what the project does - Write an intro paragraph about what this project is, what it does, and how it’s used. This section is still for SEO purposes and for keeping it simple about the value your project provides to the user who is searching for it.

Diagram (optional) - If necessary, add a diagram showing where this project fits and how it works. If it’s a CLI tool or a graphical tool, this would be a great opportunity to add an animated GIF of your project in action. Even better, adding a youtube video demo of your project to your README could be very beneficial to gaining more users.

Installation and usage instructions (for end-users) - Now it’s time to get a little bit nerdier. If a user has gotten this far into your README, you bet there’s a chance they actually want to use your project. Give instructions on how to install or use the tool. Don’t get this confused with how to contribute to this project (like help improve the code), that’s the next section. This section should only talk about how to be a consumer of the project.

Installation and usage instructions (for contributors) - Ya know the best part of open source projects? If you make something really cool, others will want to help make it better! In this section of the README, give instructions on how to pull the code down and start up the tool for development purposes. This section is usually pretty technical and may require instruction on how to build from source, but hopefully, you have a script for MAKEFILE from stuff like that. Anything you can do to make the development experience easier will help you gain more contributors.

Contributor expectations - If you are looking for contributors, make sure you set the ground rules. There’s nothing worse than getting someone who wants to help you but they don’t know how! This section of the README gives the guidelines for contributions. Do you expect someone to create an issue in the issue queue and then resolve it with a pull request? Do you want squashed commits? Do you have a pull requests template? Explain it all here.

Known issues - I already talked about this README section above so I’ll keep it short. Make a brief list of known issues here so people don’t report bugs you already know about!

=======================================
I get a lot of questions about my gear so I've created a few lists of the stuff I use. These are affiliate links. If you click and literally buy anything, it helps support the channel! Thank you.

=======================================

==============================================================

00:00 - README Rant
00:08 - A README Thinking Excercise
00:42 - Why even write a README
01:18 - How NOT to write a README
02:13 - Benefits of a good README
04:05 - How to write a good README

[nielsen]

As an university student, I like your video because of how concise it is as I dislike watching long unnecessary videos in learning stuffs online. I have never been bothered to write a readme file before but your video sparks my interest in writing one for my project. I guess I need to at least start somewhere. Thank you for sharing such helpful information.

[strandingstranger]

This video format is insane. Was about to check a few minutes of this vid just out of curiosity, but you kept me instrested the whole time. I absolutely loved the way how you explained everything. Thanks for making this video and I hope you will keep them coming.
Also, for sure will make use of these advices.

[thninja]

Outline
Title and subtitle (one line explainer)
Intro paragraph
Diagram or video (optional)
Installation instructions for users
Installation instructions for developers
Contributor expectations
Known issues
Beg for money 😉

[TotonZx]

Wow, these advices are really great, thanks for sharing them!

[adamsomari]

Finally someone that cuts to the case, while giving an overview! Thanks bro!

[bulelanibotman]

you just earned yourself a subscriber, i don't know how grateful i am for this video! i never knew how to write a readme since i am still new to programming and this video is very much appreciated

[deibit]

My God! I felt in calm when I found the steps for a good readme file in the video description. he really validated what he taught us.

[similityjoe]

Awesome video! I love the structure: bad examples first, then good example explained in a step-by-step guide. Love it :)

[zigaudrey]

As a newbies, my ReadMe goes like this: the short description of the project, what it achieves, the Steps/How to use it, and optionally, extra information like example, link, story, image result and what-not.

[Mewoi]

Underrated channel, honestly keep up the good work.

[bhartendupandya]

Very amazing guidelines. This is exactly what I was looking for. Thank you.

[kevon]

Thanks for sharing these best practices!

[mdyousufgazi]

thank you so much for these information. this channel is gem

[markspindler]

Thoughtful and well put together video. The music sounds like Vsauce 1.

[sebastianlozano]

Excellent video brother, thanks so much!

[NotTheHeroStudios]

> calls ReadMe file as a "gateway drug"
> "about to hook all these mf programmers on this drug


Perfectly explained. I have skipped out on so many things because the ReadMe didn't make sense

[ivanov]

Thanks for a good video! I’ve been looking for the best readme formula myself for some time, and eventually came to something like this as well.

Just checked my last published repo, everything is in place :)

[Actanonverba]

Great and simple advice, I loved it.
Thanks

[unidentifiednoun]

"and then beg for money" 😆that definitely sounds like a good way to end it off

[Eysvar]

Something that I try to always put in my READMEs as well are usage instructions. However, I try not to bog down the user with everything, especially if it's a larger project. That's when you maintain a wiki and/or a help section in the program itself and then point to that resource within the README.

On a less related note, I would suggest installing a couple extensions to help with spell checking and linting markdown. That way you can catch spelling mistakes and follow markdown best practices.