How To Write a USEFUL README On Github
ฝัง
- เผยแพร่เมื่อ 2 มิ.ย. 2024
- 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! - www.buymeacoffee.com/askcloud...
=======================================
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: kit.co/AskCloudArchitech/my-h...
Here's a link to my youtube "studio" gear: kit.co/AskCloudArchitech/yout...
=======================================
My website for written versions of these vids: askcloudarchitech.com
==============================================================
Github Project with THIS README: github.com/askcloudarchitech/...
Follow me on Medium: / 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
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.
Glad you liked it.
If you dislike watching long unnecessary videos in learning - why did you sign up for uni?
@@zbjz Not all universities stuffs are online. The problem with longer videos is that they feel less "interactive" while in actual lecture I could ask the instructor directly. I'm not sure if I'm making sense but yeah.
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.
Glad you enjoyed it! This type of video is certainly more of an editing challenge since its not just me sharing my screen, but they are fun and more fast pace. I don't like wasting people's time and try to keep things moving throughout the whole video.
@@LearnFastMakeThings as a fresher to kick start my career, in my GitHub projects there's not a single readme that i created! Really appreciate your effort!!! looking forward to your videos and mentors like you. ❤
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 :)
Wow, these advices are really great, thanks for sharing them!
You’re welcome!
Sir, Your way of explaination is just awesome!.
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
Glad I could help!
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.
Glad it helped!
Great explanation! and also the points you have mentioned worth the time to implement them.
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 😉
I learned A LOT in one video holyyy
thank you so much for these information. this channel is gem
Thanks!
Thanks man, very helpful!
Thoughtful and well put together video. The music sounds like Vsauce 1.
Finally someone that cuts to the case, while giving an overview! Thanks bro!
You're Welcome!
I've been looking for something like this! Great content. Looking forward to more of your videos
More to come!
@@LearnFastMakeThings looking forward to it!
Thanks for sharing these best practices!
You're so welcome!
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.
Great and simple advice, I loved it.
Thanks
You’re welcome!
Underrated channel, honestly keep up the good work.
Appreciate it!
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.
Great advice. Thanks for sharing!
> 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
Lol. Sometimes I say stuff and don’t even think about it afterwards. Love these comments that call it out
Glad that I found your channel
Welcome!
Wonderful ideas
Thank you! 😊
thanx my dear friend
Kinda disagree with the h2 subtitle. I just don't like it visually haha. But other than that, great tips! Will try them on my next projects
Fair enough!
If you are ever alone on a work project which may or may not be open source, you will most likely feel like taking time to write readme and documentation is counter productive.
It's the opposite in practice.
My own readme files are shorter and more targeted at enabling me or any future contributor to get started quickly.
- Title has to be explicit, a short description must explain why the project (module, plugin…) exists and what it does.
- An install section usually explain 3 things:
1. Read the Makefile for all convenience commands.
2. Dev environment as of the latest version.
3. What are the commands to install, build and deploy.
- An usage section invariably says the same thing: refer to the test folder.
I can be as sparse because my documentation is mostly in my code.
It happens more often than you'd anticipate that you need to revisit code you wrote years ago. Memory is selective, don't expect to remember how your own code works. Usually you will be in a rush and annoyed that you had already written and tested but have to come back for a fix, add features or port your code.
My personal workflow is to break my code into the smallest most logical methods/modules possible. I document every method (What it does, why it exists, arguments/type) and every Makefile command (what it does, arguments, example).
I like Makefile, they work like an executable Readme when properly documented. Even if your package has scripts in its description file, you can use the Makefile to call these scripts with the added benefit of the documentation.
The last piece that solidifies my documentation are automated tests. They don't need to log what they do. They need to be sequential, asynchronous, tracing where test fail. Each module/file/method should ideally have tests for its inputs, exceptions and outputs, each briefly commented as to tell what is being tested.
I have found it extremely useful with evolving languages, interpreters, compilers and environments. Even if the code does not change, external factors may break it. In a mono repo project, having one command run all tests for all modules and dependencies is a wonderful tool. Both to ensure no side effects by recent changes but also to give confidence.
Yes, this is a video on readme for github. But if you've watched it and read the comments, this one could be useful.
thanks for your thoughts
@@LearnFastMakeThings thanks for your video
thank you so much
You're welcome!
Great video!
How about a FAQ?
Sure! FAQs are a great way to explain how a more complex project works.
Also, everything answered in a FAQ should be either in the documentation, just not easily found, or obvious with a little background. Too often I found info there to be important and not specified elsewhere.
thanks!
You’re welcome
sweet!!!
thanks!
thank you
You're welcome
Wow like your content keep it up iam new nodejs
Glad you like it!
Now I have chat gpt4 write out the readme for me with the info I give it, and of course the readme comes out flawless.
That will work, as long as it’s accurate
I have a program that writes to a file in VS. When I upload everything to GetHub it fails to write to that file when the program tries to. I tried the txt extension, md extension and different paths to that file. Nothing worked. Any suggestions?
Did you check the file permissions? Is it writable by the user/group that is trying to edit it?
@@LearnFastMakeThings Where would I change the file permission on GitHub? I tried looking around there and couldn't find it. Thanks.
This is just a md in the repo right? You need to change the permissions locally then commit the permission change to the repo.
@@LearnFastMakeThings Did all that. Still doesnt work. It works fine VS but not on GetHub
Greaaat
thanks!
شكرا جزيلا
You’re welcome!
Hi
Hello!
Gateway drug, huh😂😂
keep in mind, readmes are for other developers only. companies don`t even waste their time.