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.
@@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. ❤
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
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.
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 😉
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.
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 :)
I just giggled, guys reading this, for a second imagine you just put somebody who things this is "just like a blog post" kind of video and they watch this video
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.
> 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
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.
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?
Show what you want to but don't show you face more then the page where you working You got good knowledge but you make videos with zero creativity soory if you feel bad but need to change alot to grow
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.
same, no more 2x speed with this G
Totally agree
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. ❤
Wow, these advices are really great, thanks for sharing them!
You’re welcome!
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!
Finally someone that cuts to the case, while giving an overview! Thanks bro!
You're Welcome!
Underrated channel, honestly keep up the good work.
Appreciate it!
Awesome video! I love the structure: bad examples first, then good example explained in a step-by-step guide. Love it :)
Glad you liked it!
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.
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 😉
Thank you!!! Your explanation of this was so much better than my course tutor 😂
I learned A LOT in one video holyyy
Thoughtful and well put together video. The music sounds like Vsauce 1.
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!
thank you so much for these information. this channel is gem
Thanks!
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!
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 :)
Thanks for sharing these best practices!
You're so welcome!
Very amazing guidelines. This is exactly what I was looking for. Thank you.
"and then beg for money" 😆that definitely sounds like a good way to end it off
Excellent video brother, thanks so much!
Sir, Your way of explaination is just awesome!.
Great and simple advice, I loved it.
Thanks
You’re welcome!
I just giggled, guys reading this, for a second imagine you just put somebody who things this is "just like a blog post" kind of video and they watch this video
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!
Great explanation! and also the points you have mentioned worth the time to implement them.
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
Glad that I found your channel
Welcome!
Great guide, thanks!!
> 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
So useful, thanks a lot.
keep in mind, readmes are for other developers only. companies don`t even waste their time.
Thanks man, very helpful!
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.
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
Wonderful ideas
Thank you! 😊
Thank you!
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
thanx my dear friend
Wow like your content keep it up iam new nodejs
Glad you like it!
thanks!
You’re welcome
sweet!!!
thanks!
thank you so much
You're welcome!
thank you
You're welcome
Greaaat
thanks!
Hi
Hello!
شكرا جزيلا
You’re welcome!
Gateway drug, huh😂😂
Show what you want to but don't show you face more then the page where you working
You got good knowledge but you make videos with zero creativity soory if you feel bad but need to change alot to grow
Yeah totally. Your vids are way better…