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

👇 Share with us your Github repository in the comments and I’ll add it here!

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:

1. Avoid hard-to-spell names.

2. Conduct a thorough Internet search.

3. Get the .dev or .io domain name.

4. Use a name that conveys some meaning.

5. Get feedback on the name.

6. Make sure the name sounds good when said aloud.

7. Use resources available for brainstorming names:

• VisualThesaurus.com
• Shopify Business Name Generator
• Business Name Generator

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

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:

• Figma
• VistaCreate
• Desygner
• Canva

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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.

How do I make a good changelog?

Guiding Principles

• Changelogs are for humans, not machines.
• There should be an entry for every single version.
• The same types of changes should be grouped.
• Versions and sections should be linkable.
• The latest version comes first.
• The release date of each version is displayed.
• Mention whether you follow Semantic Versioning.

Types of changes

• Added for new features.

• Changed for changes in existing functionality.

• Deprecated for soon-to-be removed features.

• Removed for now removed features.

• Fixed for any bug fixes.

• Security in case of vulnerabilities.

— keepachangelog.com

Examples

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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

👇 Share with us your Github repository in the comments and I’ll add it here!

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]