okay there are readme files that gets you to hook on and even contribute to a project and then there
are readme files that makes you question your life so in this video i will show you on ways
of creating a beautiful and useful readme files but just before that if you are new on the channel
i basically make software and hardware related projects tutorials and all sorts of random stuff
so if you like that type of stuff make sure to subscribe anyway back to readme files it is the
first thing that we see in any github page its sole purpose is to explain the project and tell
people how to install it use it and so on although creating one is easy creating a good readme
page is relatively challenging it needs to be descriptive enough to get people started however
it shouldn't be a massive 700 page word of text always remember that readme files are not equal
to full-blown documentations so how we create a good one well you first need to know the basics
of markdown which is the language that is used to create readme files as you may have already
recognized that readme files have.md extension instead of txt and that is from this reason
in markdown we got headings syntax highlighted code blocks links lists and even inline html
yes html will work in markdown but anyway i won't be going over the details of markdown in this
video but i will provide some helpful cheat sheets and online markdown editors in the description
so you can learn from there now we come to the fun part the external tools those are the tools that
makes the readme files visually appealing and in the end of this video we will look at some
examples on how to structure them correctly so let's start off by bannermaker this is a program
that is used to generate banners it is especially useful if your project doesn't have any logos in
it you just need to head over to its page and design a banner like you wish in few minutes
then download it as image and put it into your readme file it is simple but it's highly improvise
the overall aesthetics of the project then we got shields.io this one is one of the most widely used
programs ever in the readme files it basically gives brief info about wide variety of areas
code coverage build status programming language percentage size and activity to just to name a
few generating them is also pretty simple you just go to the dedicated section
and fill out the necessary information then it will automatically generates the badge for us
and then comes the amazing part which is we don't need to download and embed it into our readme
all we have to do is copy the markdown version and paste it there we go we have that next up we have
carbon now this is similar to the banner maker however it is designed specifically
for the code it will create a visually appealing version of the code which can be easily read
plus using it is also very simple we just head over to its website and there we paste our code
then we choose the language and the team we can even create our own custom theme as well
so that's nice too after that we can export it as png and embed it onto our readme that's it now
since we understand the usage of basic tools bless to cuts some good readme examples and to find them
we can head over to the awesome readme repository by mathis and like with everything i've used in
this video you can find it in the description as well anyway let's open up some random repositories
and look on their layout first we got stronghold as you can see we immediately see its logo which
is great then we have a badge and it tells us that it has 35 000 downloads which signals us that it
is probably a good project then we got a brilliant singles sentence description clear and on point
after that we got a gif it gives us the sense of simple usage then we got that followed by usage
and installation which is pretty standard then we got a cool one which is the configuration options
and it is cool because it's structured like a q a you want to turn on stealth mode your mac will not
respond to icmp ping requests you want to do this then there's that and so on it is very descriptive
then we got how to contribute acknowledgements and donations which is typical now we can move on to
our next example and that is markdownify just like in the previous example we start off with
a nice logo and a heading followed by a single sentence summary which answers the question of
what is this and it is followed by badges then we got a gif again demonstrating to usage
after that we got key features and this is really nice to include as well because before using the
program it will tell you that whether it is good for your use case or not in some larger projects
you can find index on here as well then we got usage download and rest of the expected sections
moving on we got clairvoyant or maybe i should say clairvoyant anyway this is a great example
on a complex project i just mentioned again we start off by a nice logo followed by patches
if you have noticed we got a common theme going on at that point
then we got basic overview with two sentences followed by descriptive step-by-step images
and right after that we got the demo gif then we got installation instructions followed by usage
and as you can see the usage is divided into separate parts because the project is rather
complicated which is good practice to use it on complicated projects then we got reference to
other projects notes and finally the contribution now we look at our final example which is color
ls and when we open it up we immediately noticed the coloring in this one i won't go over each
section individually because we did it multiple times and this project is pretty much the same
however this project is all about coloring the ls function outputs so if you look we can easily
notice that the readme is flooded with the sample images and that is a really nice thing on projects
like this by the way if you want to learn how to use it i can make a dedicated video about it
so just colorize the like button and let me know anyway at that point we got clear image about
how readme files should be structured and that is the following first we start off with logo
or a banner then we follow that up by related badges but don't flood it with hundreds of badges
just the descriptive and required ones after that we give a one or two sentence description then if
our project is suitable we gave a gift demo and we follow that one by installation instructions
and usage finally we add additional notes contribution license and donation information
so to prove that this structure works i managed to turn the repository of my github project
from this to this which is great improvement and if you are curious about the guitar project you
can find it in the top right corner and that said we basically concluded this video so now you know
how to create better and beautiful readme files if you find that useful make sure to
hit the like button and subscribe to see more content like this see you next time take care