What exactly are readme files? I'm sure if you've ver been to GiHub or downloaded software before you've probably seen them. What a readme file is is a file that contains all relevant information about a piece of software. In some cases, it can serve as the software or applications documentation source.
One of my favorite parts about uploading projects to GitHub is working on the readme file that will go with the software. Today, I want to share with you what I have learned about writing readme files as well as a few resources you can use to help spruce up your readmes. I will have links to all relevant resources, articles, and repos.
Some of my favorite readmes that I have made are StreamOS,
Knights vs Goblins, and Random Pass Word Generator (Python). I like them for different reasons but, they all have one thing in common: They were a BLAST to work on.
Tip 1: Inserting an center image.
One thing I always like to do is make a banner or graphic for my repo to give it that visual pop! But, I always hate how the image is never centered. One thing you can do is use the following html code to center your image:
<p align="center">
<img src="[YOUR_RAW_IMAGE_URL]" alt="[YOUR_ALT]"/>
</p>
This will also work for any badges or text that you would like to have centered.
Tip 2: Less is more
It may be tempting to put everything in the read me. How to install it, run it, set up the code, etc. But, long readme files are kind of a slog to get through. Try to keep only the most important information in the readme. If your application has a lot of documentation, you can
create a
/docsfolder in the root of your project, where you can keep additional markdown documentation that can be browsed directly from your code hosting platform (assuming GitHub).
Documentation 101: creating a good README for your software project by Erika Heidi
Tip 3: Consider creating a wiki:
This is not as tricky as it sounds. Turns out, every repo that you upload to GitHub comes equipped to have it's own wiki. According to GitHub:
You can host documentation for your repository in a wiki, so that others can use and contribute to your project. Every repository on GitHub.com comes equipped with a section for hosting documentation, called a wiki. You can use your repository's wiki to share long-form content about your project, such as how to use it, how you designed it, or its core principles.
Going back to tip 2, if your particular repo has a need for a lot of long-form documentation, then a wiki may be what you're looking for. To learn more about GitHub wikis you can go here
Tip 4: Consider adding more .md files as necessary:
A couple of other files you can add to your repo that you may need are the contribute.md and the code_of_conduct.md. Honestly, I have never added these because I have wyet to make a repo that really needed them. I link to an email for submitting contributions and reporting bugs but, I have never really added either of these documents to one of my repos. BUT, if your project needs them, I definitely recommend you go check out the linked articles and learn more.
I really don't have many more tips and tricks. Creating readmes isn't an exact science but, there are some rules and formatting guides that you can follow that will not only make your readmes stand out but will also make them functional. What I can do however is link you to some of my favorite resources that I have used to learn how to create better readmes.
- How to write README files like a pro by Olaf Górski
- GitHub README Templates
- GitHub PROFILINATOR by rishavanand
- GitHub Profile README Generator by rahuldkjain
- shields.io
- simple icons (AWESOME site. I use this one almost everytime I make a readme)
- awesome-github-profile-readme by abhisheknaiidu (This is a really good repo to get inspiration for your profile README).
- awesome-readme by matiassingers (Another good source to get inspiration for your README files).
- creative-profile-readme by coderjojo (Even MORE README examples)!
- GitHub Badge Generator by michaelcurrin (This is a site that I use every time I make a repo. I use this in conjunction with the simple icons site)
So that about covers it. If you have any sites that you use when creating your readmes, let me know. Thanks so much for reading and have a wonderful day/night!
Top comments (0)