A beginner's guide to readme files
Tags: github, beginners, markdown
Published: 2022-12-17 21:26:07

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](https://github.com/kurtissfrost/streamos), 
[Knights vs Goblins](https://github.com/kurtissfrost/knights-vs-goblins), and [Random Pass Word Generator (Python)](https://github.com/kurtissfrost/Random-Password-Generator). 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:

```html
<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 `/docs` folder 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](https://dev.to/erikaheidi/documentation-101-creating-a-good-readme-for-your-software-project-cf8) by [Erika Heidi](https://dev.to/erikaheidi)

---

## **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](https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis)

---

## **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](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) and the [code_of_conduct.md](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project). 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](https://dev.to/grski/readme-file-structure-and-sections-pm8) by [Olaf Górski](https://dev.to/grski)
- [GitHub README Templates](https://www.readme-templates.com/)
- [GitHub PROFILINATOR](https://profilinator.rishav.dev/) by [rishavanand](https://github.com/rishavanand)
- [GitHub Profile README Generator](https://rahuldkjain.github.io/gh-profile-readme-generator/) by [rahuldkjain](https://github.com/rahuldkjain)
- [shields.io](https://shields.io/)
- [simple icons](https://simpleicons.org/) (AWESOME site. I use this one almost everytime I make a readme)
- [awesome-github-profile-readme](https://github.com/abhisheknaiidu/awesome-github-profile-readme) by [abhisheknaiidu](https://github.com/abhisheknaiidu) (This is a really good repo to get inspiration for your profile README).
- [awesome-readme](https://github.com/matiassingers/awesome-readme) by [matiassingers](https://www.github.com/matiassingers) (Another good source to get inspiration for your README files).
- [creative-profile-readme](https://github.com/coderjojo/creative-profile-readme) by [coderjojo](https://www.github.com/coderjojo) (Even MORE README examples)!
- [GitHub Badge Generator](https://michaelcurrin.github.io/badge-generator/#/generic) by [michaelcurrin](https://www,github.com/michaelcurrin) (This is a site that I use every time I make a repo. I use this in conjunction with the [simple icons](https://simpleicons.org/) 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!

![signature](https://i.imgur.com/aXaiikD.png)