How to create an effective GitHub profile README?

When you visit your profile on GitHub, you'll see that it stands out because of the inclusion of photographs, social media links, GitHub statistics, and blog links. The README feature on GitHub profiles makes this possible.

GitHub Profile README
A GitHub profile README helps developers show both the developer as well as personal self out on GitHub.

A new feature from GitHub lets users build a profile-level README that will be prominently displayed on their GitHub profile. Let's look at how to make this functionality available on your GitHub profile.

Ever since its inception in 2008, GitHub has experienced an immense amount of growth. It has grown massively and now hosts accounts of 83 million developers and more than 200 million repositories.

This huge growth in the number of users means increased competition among the developers to make themselves stand out.

At the outset, GitHub might look competitive. But with the numerous functionalities that it has added over the years, standing out on GitHub is not as difficult as it may seem.

Here are a few ways developers on GitHub can utilise to differentiate themselves.

  1. Repositories: Every repository that developers create or contribute to gets displayed on their profile. This is advantageous for them since the huge GitHub userbase then has access to it and can get an idea of their proficiency in coding.
  2. Contributions: The mere presence of developers on GitHub is not enough. A GitHub profile with consistent contributions, and contributions to open-source projects indicates the developer’s keen interest in programming and gives them the necessary edge to beat the competition and bag the job.
  3. Open-source projects: GitHub is practically the hub of open-source. Any developer can contribute to these open source repositories. These contributions might not look as significant at the outset but these small contributions have a compounding effect in the long run and can act as proof of teamwork and the eagerness to contribute, the two key attributes that provide an edge in any corporate setup.
  4. GitHub profile README: This is one of the easiest, most interesting, and one of the best ways (if not the best way) to stand out on GitHub.

A GitHub profile README file is a guide that gives a detailed description of a developer and appears at the top of a developer’s GitHub profile page. In a more lucid language, one can consider the GitHub profile README as a well-written and heavily decorated long-form Instagram bio, just not on Instagram.

Earlier, developers could only use README files to give detailed information about any repository they created. GitHub has undergone a lot of changes since then and today attractive READMEs have become one of the best instruments to grab the attention of visitors.

A detailed explanation of Sy Rashid’s README would serve as a very good example to establish a good understanding of a GitHub profile README.

Sy Rashid's GitHub profile README

Sy Rashid is a nuclear engineer turned developer from Portugal. After graduation, Sy went on to work at various jobs at breweries, launch a wine brand, code an algorithm to find best-selling eCommerce brands, and became a venture capitalist only to return back to school and become a full-stack developer.

Sy’s profile README incites emotions of happiness with a warm greeting at the top, followed by a concise three-line introduction of his present life scenario. He then brings out his coder self in its truest form with crisp lines of code followed by a quick rundown of his programming language skills, and other different tools he uses in his free time. Sy Rashid finishes off his README with GitHub stats, visitors, PR, and open-source badges.

An excerpt from Sy Rashid's README showing the aspect of his personality

What should go in a README file?

Since GitHub README is a reflection of developers’ life it should not just include code but also other things that constitute their day-to-day life. Therefore, to make sure that developers make a good first impression whenever someone visits their profile, they need to think through and carefully curate the content that goes inside their profile README.

It is a good idea for developers to map out a plan before diving deep into making a README for their profile. Here is a list of a few things developers can use to add a pinch of flair to their profile README.

About Me: An “About Me” section is a must-recommended section that should be added to a GitHub profile README. It can serve as developers’ introduction to the visitor. Developers can write all about themselves here. It is advised to make the “About Me” section as interesting as possible by adding fun and quirky information about themselves. This will be helpful in hooking the visitors from the moment they land on the profile.

Sy Rashid's GitHub profile README header incites emotions of happiness 
Sy Rashid's GitHub profile README section gives a brief about his present life scenario

GitHub stats: GitHub statistics is an important tool for developers to let visitors know the importance of their repositories. GitHub statistics include the number of views, unique views, clones, and unique clones. Currently, GitHub only provides statistics for the last 14 days. These statistics prove very helpful in gaining insights into the kind of interesting projects a developer creates. Developers can set this up very easily on their README by visiting this open-source repository.

GitHub stats are simple markdown images that give the real-time status of a developer's GitHub repositories

Badges: A very good way of highlighting skills on profile README is through badges. badges provide a good range of styles that developers can use as per their liking to beautifully showcase their skills and knowledge of programming languages they exhibit. badges on GitHub are a quick, interesting and readable way for developers to give visitors an idea of their skills. 

Blog Posts: For a lot of developers, blogs complement their knowledge and skills. This helps them grow in their careers and impact the careers of other developers in the process. Listing these blog posts will serve as additional insight into the developer’s knowledge apart from the one that is evident on GitHub.

The below screenshot is a list of blog posts that come straight out of Apoorv Tyagi’s GitHub profile README. By providing a list of these blog posts Apoorv moves away from just writing about code to displaying his interest in writing as well as providing proof of their in-depth knowledge of the basics of programming.

With a list of blog posts in their profile README, developers show the other ways they add value by utilising their knowledge 

Social media handles: With the increasing number of developers on social media platforms, it has become increasingly important for them to make their presence felt and as such developers should not just add links to their social media handles but also ensure they put up relevant high-quality content as well.

Social media links on any developer's profile README gives encourage the visitors to unravel aspects of a developer's life other than coding. 

GIFs and Images: With the attention span of human beings now limited to just 7 seconds, a GIF or an image at the top of a profile README can make the visitors stick to the developers’ profile even if the content inside the README is not enough to make the visitors stick around.

There are numerous other features that can be used to create a profile README that grabs visitors’ attention. But, the decision regarding the correct usage of such features should be taken with an aim to make the profile README more creative, concise, and authentic.

Why Is It Important to Have a GitHub Profile?

  • To promote your work and network with other developers, coders should create a GitHub profile. Programmers are able to create projects and write code for repositories that do not belong to them thanks to GitHub's collaborative features. However, GitHub stores all developer-written code under their individual GitHub profile.
  • A strong GitHub profile serves as a digital CV, showcasing each programmer's actual skills. Coders can promote their work to prospective employers with ease thanks to GitHub profiles.
  • You may communicate with other programmers and public repositories on the website by creating a GitHub profile. Through GitHub, programmers may connect with one another, share advice with other software engineers, and come up with original solutions to coding issues for their own projects.
  • Through your GitHub contacts, you might be able to learn how to use new technologies or find out about job openings.

How to create a GitHub profile README?

You may add additional text to the profile bio using the README function on the profile level. Because it supports markdown, you may experiment and expand your creativity with additional visual material (GIFs are the greatest part!). This README is considerably more noticeable because it is positioned above pinned repositories on your profile page and uses as much space as you'd like above the fold of the webpage.

Follow these simple steps to create a GitHub profile README-

Step #1: Log into GitHub and go to your profile
Step #2: Click on "Repositories"
Step #3: Click "New"
Step #4: Make the repository’s name the same as the username
Step #5: Ensure that the repo is set to "Public"
Step #6: Check the box that says "Add a README file"
Step #7: Click "Create Repository"

Necessary pre-requisites for creating a profile README

As soon as these steps are completed a green box will pop up saying that the repo just created is a special one (since it has the same name as that of the username) with an “Edit README” button at the bottom.

The most important step to create a README file

Developers can then click on this button to customise their README the way they want it to.

Suitable formats to write a README file

Developers can write and save a readme file in any text file format. Formats may include .txt, .doc, etc. There are other formats as well such as plain text, reStructuredText (commonly used in Python), and Textile. The readme file format should be modified to the appropriate system and the corresponding text program depending on the platform the software is supposed to run on. This ensures that the file can be read by the word processor.

As per the recent trends, developers mostly use the format. The extension “.md” indicates a markdown format. Markdown uses straightforward formatting characters to convert text into HTML. In order to keep readers' attention and encourage them to read till the final alphabet, a README file needs to have a well-designed structure and present content in a concise way.

What is a README file used for?

GitHub profile README can be considered synonymous with a window into a developer’s life. Any developer can use it to provide various details about themselves that are generally not expressed through code. Following are the various ways developers can use GitHub profile README to the best of their advantage-

  1. Customisation: The GitHub profile README provides information about developers’ profiles to the profile visitors. Since a README can be written in markdown format, it becomes easier for developers to customise content. Additionally, developers are free to add as much text to their profile README.
  2. Showing the importance of code: Developers can add various sections to their profile README, that describe the importance of the repositories they create. One very good example of this kind would be GitHub stats that provide deep insights about the engagement on developers’ repositories as well as the languages they use the most. This can prove very beneficial for recruiters looking out to hire new talent.
  3. Quick overview of skills: With the help of badges or icons, developers can give their profile visitors a quick glance at their skills. These badges will make it easier for visitors to gauge the value proposition of developers and make decisions regarding carrying out further interactions with them.
  4. Adding another layer to the developer’s personality: Since the content that goes inside a README file is in full control of the developer, they can provide additional information enabling them to add layers of their personality that are not associated with code.

Benefits of Having a Profile README

  • Demonstrating your abilities: By posting pictures, gifs, or videos of the things you've made or worked on with others, you may emphasize your noteworthy abilities and achievements.
  • Personality: You may add your own unique approach and personality, which is something that is harder to emphasize in the resume's black-and-white language.
  • Employability: Potential companies may find you more appealing if you have a profile README. It demonstrates your initiative and coding enthusiasm, which might help you stand out from the competition.
  • Collaboration: On the GitHub platform, programmers can communicate and work together. Other GitHub users may determine if you have a certain talent they require for a project by looking at your profile's README, which provides them the opportunity to collaborate.

Examples of effective GitHub profile READMEs

Here’s a list of 5 awesome GitHub profile READMEs that caught our attention and might serve as a source of inspiration for other developers while creating their profile READMEs-

  1. Raymond Li: Raymond is on top of our list mainly because of two reasons- the conciseness in his content as well as the dynamic banner in GIF format right at the top. It grabs the attention of the visitors from the moment they land on his profile and the concise content present further enables the visitor to go through the entire README with ease.
Raymond Li's GitHub profile README
  1. Aditya Pal: This profile has something from every aspect of Aditya’s life. A minimal GIF at the top is the perfect start for a profile README for a developer who wants the visitors to quickly shift towards the details that matter. Further segments of this profile README bring out other details about Aditya’s life that involves his interest in designing, chess, his social media presence, achievements as well as his code proficiency.
Aditya Pal's GitHub profile README
  1. Apoorv Tyagi: Apoorv’s README is interesting solely because of the fact that he does not let the attention of the visitor waiver from his README and paints a picture of himself as a coder who writes articles on programming, is serious behind his keyboard but funny when away from it.
Apoorva Tyagi's GitHub profile README
  1. Emily: This README is the go-to README for someone who is obsessed with something, which in Emily’s case, is Anime. Even though there is limited information that has been made available by Emily on her README, she has definitely managed to bring out her love for Anime in the best way possible which makes her profile polarising and attention-grabbing for any Anime lover.
Emily's GitHub profile README
  1. Mpho Mphego: Mpho’s README is very minimal and concise. He hasn’t gone too overboard with the design. He has put up a simple GIF at the top that greets a visitor with information about himself. Mpho then follows this up with information on his current venture into machine learning and cloud architecture courses. Mpho later lists out ways for people to connect with him by providing his e-mail address and a link to his Calendly. Mpho rounds OFF his README by providing insights into his repository, his recent blog posts, and links to his social media profiles at the bottom.
Mpho Mphego's GitHub profile README

Final Words

GitHub provides developers with a good platform to showcase their coding skills. It looks like an attractive improvement on a norm that many GitHub users are already accustomed to including README at the profile level. The profile README thus serves as the perfect initial touchpoint for any visitor. Hence, to make sure that developers leave a long-lasting impression on the visitors and make sure they keep coming back for more developers must reasonable amount of time on their profile README.  

Since the profile README is fully under the control of the developers they can keep on updating the content on a consistent basis and build up credibility that rewards them with long-lasting benefits.


What is the README project on GitHub?

The README Project is a component of GitHub's continuous initiative to give the developer community more power. It's a dynamic environment where you may interact with the community and investigate the history, difficulties, technology, and culture of the open-source community.

What distinguishes a portfolio from a GitHub profile?

A portfolio includes samples of finished projects, coding language expertise, and acquired technology. A user's GitHub profile allows them to display both active and finished projects. Through the contribution chart tool on GitHub, programmers may also showcase their commitment to quality work and their love of coding.