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!
Begging for money! – Don’t be ashamed to ask for money. Seriously! You put a lot of effort into this project and if someone likes it they might just throw you a couple of bucks. You can add a link to Buy Me a Coffee! – https://www.buymeacoffee.com/askcloudtech
=======================================
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.
Here’s a link to my home office gear: https://kit.co/AskCloudArchitech/my-home-office-gear
Here’s a link to my youtube “studio” gear: https://kit.co/AskCloudArchitech/youtube-recording-gear
=======================================
My website for written versions of these vids: https://askcloudarchitech.com
==============================================================
Github Project with THIS README: https://github.com/askcloudarchitech/go-rest-api-kubernetes-example
Follow me on Medium: https://medium.com/@askcloudarchitech
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
Comments are closed.