GitHub repository with the final README.md file can be found at the end of the post.
Having a GitHub account in today’s world is a must-have for any software developer. In this series of posts, I’ll show you how to create a striking README.md file to attach to your GitHub profile. If you want to see an example of the final result, take a look at my GitHub profile!
Note: my GitHub profile's README file may have changed over time. To see the exact same code demonstrated throughout this series, check out this repository.
Git vs. GitHub
First of all, if you’re not familiar with Git, it’s a technology that is widely used by almost every software project nowadays. The main feature of Git is the ability to keep your code in “repositories” and improve the collaboration between several developers who may be working on the same code at the same time. Think of it as a Google Doc for programming. Here are some sites to learn about Git if you’ve never used it before: Git Documentation, Learn Git Branching.
Now, a common misconception is thinking that GitHub is the same as Git. While GitHub is based on Git (for the majority), they’re two different things. GitHub is what you see (front-end): the user interface, the buttons, the menus, the images, etc. While Git is the technology used underneath (back-end): the ability to create and manage repositories, commit changes, share your code, collaborate with others, etc. Other sites/platforms are also based on Git, for example, BitBucket or GitLab.
So why GitHub? In my experience, almost all developers I’ve met keep their repositories on this platform. A lot of social networking sites have integrations to add your GitHub profile to your list of links or have the ability to embed your repositories in a post (for example, Polywork). And in my personal opinion, I think it’s easier to use. The UI/UX is beautiful, it has a ton of features that they keep improving regularly, and it’s 100% free!
About README.md files
Whenever you create a new repository, it is a best practice to create a README.md file at the root of your project. This file needs to explain the basics of your project: what it is, what it does, and how to install/use it. It’s basically a “welcome” page for new developers that want to use your code. Here’s a very nice example of a README.md file for the Official Jenkins Docker image repository.
GitHub has the feature of attaching a README file to your profile to introduce yourself and/or give a summary of your GitHub page for new developers visiting your profile. You are free to personalize this file with whatever information you want to show to the public. Some people use images or GIFs, embed videos, add links, or give CTAs here. Think of it as a tiny website where you get to show off your work, your hobbies and let people know who you are and what you do.
Inspiration
When I started creating my README, I was inspired by this GitHub profile. Then I noticed she has a repository with a compilation of some other awesome GitHub profiles, which inspired me even more! I didn’t know about a lot of the features that could be added to README files; I discovered them after I saw all these great profiles.
Before reading the rest of the series
If you’re new to Markdown, they may seem a bit complicated or overwhelming. But not to worry! In this series of posts, I’ll guide you through all the steps I did to get my README file up and running, even if you’re new to all this.
If you’re new to Git, I do recommend you first get a sense of the basic terminology such as repository, blob, commit, local/remote, branch, etc. I found this article on Google. It may help you to have a rough idea of the theory. You don’t really need to know Git in order to follow the series. You can just follow the steps and still get the final outcome. However, it may seem a bit confusing if you don’t understand the concepts behind it.
Recap
GitHub is based on Git, but they’re not the same thing. Git is the back-end part, and GitHub is the front-end part.
README.md files are used to explain the basics of a repository: what it does, how to install, and how to use it.
In GitHub, you can attach a README to your profile to welcome your readers.
Don’t miss any articles! Remember to subscribe at the bottom of the page to receive email notifications as soon as new content is published. ✨
-Alex
Comments