VIDOVA.ai

Posted on Apr 3, 2022 • Edited on Jul 22, 2022

Take Your Github Repository To The Next Level 🚀️

#beginners #github #git #career

I’ve been using Github for a very long time now, and along the way I’ve been gathering a step-by-step guide on creating the perfect Github repository. If you haven’t guessed already, this article is an enhanced version of that guide.

So without further ado, let’s get started!

Step 0. Make Your Project More Discoverable 🚀

— Inspired from Github Docs.

To help other people find and contribute to your project, you can add topics to your repository related to your project's intended purpose, subject area, affinity groups, or other important qualities.

With topics, you can explore repositories in a particular subject area, find projects to contribute to, and discover new solutions to a specific problem.

To browse the most used topics, go to https://github.com/topics/.

Examples

Repository	Topics
chroline/well_app	macos productivity ios mobile webapp flutter happiness mental-health wellbeing
aimeos/aimeos-typo3	php ecommerce marketplace vuejs performance vue shop json-api seo typo3 ecommerce-platform e-commerce b2b typo3-extension aimeos

Step 1. Choose A Name That Sticks ✏️

— Inspired from Forbes.

Finding the right name for your project can have a significant impact on your success.

The wrong name can do worse than fail to connect with users. In contrast, a clear, powerful name can be extremely helpful in your marketing and branding efforts.

Here are 12 helpful suggestions on how to come up with a winning name for your project:

Avoid hard-to-spell names.
Conduct a thorough Internet search.
Get the .dev or .io domain name.
Use a name that conveys some meaning.
Get feedback on the name.
Make sure the name sounds good when said aloud.
Use resources available for brainstorming names:

Examples

Repository	Name	Description
chroline/well_app	Well App	😀 improve your productivity and long-term happiness in just 21 days.
ai/size-limit	Size Limit	Calculate the real cost to run your JS app or lib to keep good performance. Show error in pull request if the cost exceeds the limit.

Step 2. Display A Beatufiul Cover Image 🤩️

There’s no doubt that projects with eye-catching images usually perform better than those without these elements.

Users are more likely to support a project that has an attention-grabbing cover image, because it creates a sense of professionalism and creativity.

But you don’t have to be a designer to create amazing visuals for your project, because there’s a dizzying amount of free graphic design tools on the Internet:

Examples

Repository	Cover Image
chroline/well_app

Step 3. Add Badges To Convey More Information 🔥

Ever noticed those small images sitting at the top of the most performing Github projects? They’re called badges, and they can be used to show more information without using any words.

Here are some examples:

Badge	URL
	`https://img.shields.io/badge/Medium-12100E?style=for-the-badge&logo=medium&logoColor=white`
	`https://img.shields.io/badge/Hashnode-2962FF?style=for-the-badge&logo=hashnode&logoColor=white`
	`https://img.shields.io/badge/dev.to-0A0A0A?style=for-the-badge&logo=dev.to&logoColor=white`
	`https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white`
	`https://img.shields.io/badge/HTML-239120?style=for-the-badge&logo=html5&logoColor=white`
	`https://img.shields.io/badge/Dart-0175C2?style=for-the-badge&logo=dart&logoColor=white`

You can find all of these and more in the Shilds.io website. You can also use Badgen to quickly generate new badges for your project!

Examples

Repository	Badges
ajeetdsouza/zoxide
alichtman/shallow-backup

Step 4. Write A Convincing Description 📄

— Inspired from 18F.

This is your chance to explain the project in one paragraph. If you do this well, you can captivate the reader into exploring more of your project and eventually using it!

In general, the description should answer a short list of basic questions:

What is this repo or project?
How does it work?
Who will use this repo or project?
What is the goal of this project?

If you follow these steps, not only will it be easier for developers to know how to become involved with the project, but it will be easy for non-coders to understand what the code is designed to do, and how they too can become involved!

Examples

Repository	Description
ai/size-limit	Size Limit is a performance budget tool for JavaScript. It checks every commit on CI, calculates the real cost of your JS for end-users and throws an error if the cost exceeds the limit.
aimeos/aimeos-typo3	Aimeos is THE professional, full-featured and high performance e-commerce extension for TYPO3! You can install it in your existing TYPO3 web site within 5 minutes and can adapt, extend, overwrite and customize anything to your needs.

Step 5. Record Visuals To Attract Users 👀

People love animated imagery! You can use GIFs to visually show many things:

How your program is used.
The best features of your program.
A visual guide to achieve some specific task.

And there’s a wide variety of free tools that you can use to create said videos, including but not limited to:

Ascii Cinema to record your terminal sessions.
Loom or OBS to record any part of your screen.
Veed to edit videos online.

Examples

Repository	Visuals
create-go-app/cli

Rebilly/redoc

Step 6. Create A Detailed Installation Guide ✅ (optional)

If the user has to install your program before using it, you should add a detailed section that explains how the user can do it. Here are some general rules to follow:

Don’t jump any steps.
Have different sections for each operation system (Linux, macOS, Windows).
Show how the user can fix the most common errors.

I also recommend using the HTML <details> tag to create a collapsing menu. It results in a much cleaner README file!

Examples

Repository	Installation Guide
easybase/easybase-react	Getting Started
emalderson/thephish	Installation

Step 7. Create A Practical Usage Guide 🏁

You should show the user examples of how they can use your software, and the expected outputs too if you can. This will help prevent confusion about how your program works, and create a better bond between your software and its users.

Examples

Repository	Usage Guide
create-go-app/cli	Production-ready project templates
iharsh234/WebApp	Usage

Step 8. Answer Common Questions 🤔

This section, also called the “FAQ” (frequently asked questions), should be left to contain the most common questions that your users ask. Too many people asking where to find the settings panel? Put the answer in here so no one has to ask again.

Examples

Repository	FAQ
choojs/choo	Why is it called Choo? Is it called Choo, Choo.js or...? Does Choo use a virtual-dom?

Step 9. Build A Supportive Community 🤗

There’s nothing better than a nice community! If the user ever needs help, they can reach out, ask a question, and get a valuable answer to their problem!

Here are 3 general steps towards building a great community for your project:

Step 9.1 - Let’s Connect!

Add a “Let’s Connect!” section to your README, where you reveal several links to the platforms where your community resides: Discord, Gitter, Slack, or even simply an email address!

Step 9.2 - Discussions (optional)

You can use GitHub Discussions in a repository as a place for your community to have conversations, ask questions, and post answers without scoping work in an issue.

Here’s a guide on how to enable discussions for your repository.

Step 9.3 - Code of Conduct

— Taken from Github Docs.

Adopt a code of conduct to define community standards, signal a welcoming and inclusive project, and outline procedures for handling abuse.

A code of conduct defines standards for how to engage in a community. It signals an inclusive environment that respects all contributions.

You should have a CODE_OF_CONDUCT.md file in your repo that explains all the details that need to be known.

Here’s a guide on how to create a code of conduct for your community.

And here’s a template of a CODE_OF_CONDUCT.md file that you can freely use in your own work.

Examples

Repository	License
microsoft/TypeScript	`CODE_OF_CONDUCT.md`
vercel/next.js	`CODE_OF_CONDUCT.md`

Step 10. Create Contribution Guidelines 👷

— Inspired from 18F.

Since open-source inherently welcomes outside contributors, it’s important to explicitly state how they can help and what they can help with. This document should answer the following question: How can outside contributors become involved?

You should include a CONTRIBUTING.md file in your repo, which outlines the following:

If there are any additional setup steps specific for development.
Whether there are explicit Instructions for running tests before contributions are accepted.
Whether potential contributors should ask before they make significant changes.

Here’s a template of a CONTRIBUTIONS.md file.

Examples

Repository	License
microsoft/TypeScript	`CONTRIBUTING.md`
vercel/next.js	`contributing.md`

Step 11. Choose The Right License ©️

— Inspired from Github Docs.

Public repositories on GitHub are often used to share open source software. For your repository to truly be open source, you'll need to license it so that others are free to use, change, and distribute the software.

There’s a choosealicense.com tool online that can freely help you choose a license for your project. You should include a LICENSE file (file extension is optional) that includes the legal excerpt that’s accompagnied by your chosen license.

But remember that you're under no obligation to choose a license. However, without a license, the default copyright laws apply, meaning that you retain all rights to your source code and no one may reproduce, distribute, or create derivative works from your work.

Examples

Repository	License
microsoft/TypeScript	Apache License
vercel/next.js	MIT License

Step 12. Plan Your Future Roadmap 🚗

You should add a page to your project’s wikis that describes your plans for the future. This is your chance to specify your upcoming plans, and to show that your project has a long-term future. Be ambitious within the bounds of realism.

What features are you going to add in the next version? When do you plan to release those features that users can’t wait for? Answer all these questions in the roadmap.

Examples

Repository	Roadmap
microsoft/TypeScript	https://github.com/microsoft/TypeScript/wiki/Roadmap

Step 13. Create Github Releases 📌

Github has a releases feature that lets you show a history of your project’s versions. In every release, you should write a changelog that describes what’s new and what was removed from that version.

Examples

Repository	Releases
release-it/release-it	https://github.com/release-it/release-it/releases/tag/14.14.0
ryanoasis/nerd-fonts	https://github.com/ryanoasis/nerd-fonts/releases/tag/v2.1.0

Step 14. Customize Your Social Media Preview 🤩️

— Inspired from CSS Docs.

You can customize the image displayed on social media platforms when someone links to your repository.

Until you add an image, repository links expand to show basic information about the repository and the owner's avatar, but you can customize it to look more attractive!

Examples

Repository	Social Preview
saikou-app/saikou

vercel/next.js

Step 15. Launch A Website 🚀

After doing all of the above tasks, there’s really only one step left that can really take your repository to the next level: launching a website!

You can use Github Pages to freely host a website straight from your repository. Creating a custom webpage for your project allows you to be more creative, and dramatically increases your chances to be discovered by search engines.

Don’t miss your chance to get that extra traffic!

Examples

Repository	Website
iharsh234/WebApp	https://iharsh234.github.io/WebApp/
gitpoint/git-point	https://gitpoint.co/

Credits: ❤️

Thanks to Benny Neugebauer for suggesting sections 12 and 13.
Thanks to Paul McGann for suggesting OBS in step 5.

Those were 15 steps towards creating a killer Github repository. They’re not rocket science, but they can have a great effect on the success of your project!

[Deleted User]

Top comments (44)

Benny Code • Apr 3 '22

You picked great live examples! Thank you very much for sharing.

What also makes a GitHub repository attractive to me is when they are using GitHub releases and proper changelogs. Example: github.com/mui/material-ui/release...

Using GitHub pages for API documentation is also important. Example: github.com/vazco/uniforms/tree/gh-...

VIDOVA.ai • Apr 3 '22 • Edited

Thank you for these suggestions! 👍
I will be updating the article, and giving you the credits!

Benny Code • Apr 3 '22

Oh, that's cool! Thank you. 😊

Dhanush N • Apr 3 '22

You can add much more such as profile viewer count etc.

You can have a look at my GitHub repository as well regarding stats & github actions 🙂

VIDOVA.ai • Apr 3 '22

Very interesting, thanks!

Jakub T. Jankiewicz • Jan 24 '23

They are not actually for repositories only for profiles, it will look odd if you do the same on your project.

Dhruv Mehta • Apr 5 '22

Damn this is really a great article. I know that readmes are important and they make the project even better. But here you mentioned a few things about which I was completely unaware of. Thanks for sharing!

VIDOVA.ai • Apr 6 '22

I'm glad you liked it! 👍️

Paul McGann • Apr 8 '22

Nice write up and something I will be using for future projects. There is another piece of screen recording software I thought useful to mention it is called Open Broadcaster Software (OBS) obsproject.com/. You can capture a whole screen or specific windows or a section of a screen. Best of all it is free and open source.