5 Tips to Improve Your GitHub Project

Maybe you created a brilliant tool and want it to remain free and maintained with help from the community, or maybe you want to use it as a portfolio piece to get a job. Either way you need to polish it and make it easier for new users and/or contributors to digest.

Let's remember that version control was born to help several people contribute to the same project. If you do not follow a standard and do not help others understand what the repository is about, developers may feel a bit lost and leave. Here are five recommendations to increase your project's visibility and the chances of getting hired or receiving a pull request 😉.

But... what is this? READ ME!

Mauricio from the comedy series Aida. Taken from Tenor.

That is literally the first question someone asks when they open your repository for the first time. What is this project about? Which technologies does it use? How can I run it locally after cloning it?

That's why READMEs exist. If you create a file called README.md in your local repository, GitHub will render whatever you put there, which is why it should be one of the first files you create. It's the first thing people read.

Threadly open source project https://github.com/ragnarok22/threadly

This file contains the basic and necessary information about your project. It should include at least:

1. Project name: The identifier for your project. Every project needs a name.
2. Short description: A concise explanation of what your software does.
3. Badges: Quick, visual labels that show relevant information such as license, coverage, supported programming language version, and more. Tools like Shields.io make them easy to create.
4. Installation: After cloning the project, people need to install dependencies and run it locally. How should they do it? Even if you're using a common standard (yarn or npm for Node, for example) you still need to document it. Maybe the person has never done it before or doesn't know the process. Guide them step by step so they can install and run it locally.
5. Deployment: If you use an open license and people are free to deploy it wherever they want, explain how to build or deploy it 🚀.
6. How to contribute: Every project has standards, methodologies, and lifecycles. Contributors need to follow those rules so that no matter how many collaborators you have, the code stays clean and consistent.

Beyond the README, GitHub recommends adding a code of conduct, a license (even free and open source software needs one), and issue templates so people know how to report bugs or propose ideas. Here's a fantastic README editor that can make the process easier.

Testing, testing... 1, 2, 3

Bart Simpson. Taken from Tenor.

Don't give me that look. They have to be done. Tests are an essential part of software. No matter if you run your program, click around, and it works, tests help document the behavior you expect—and the one you don't. By reading the tests we get a sense of what each part of the code is supposed to do and we confirm that it works. Sure, having tests doesn't cover 100% of the scenarios, but it protects us from all the oops moments we can imagine.

Every framework, library, or programming language has its own way of writing tests, and there are even libraries that make them easier. It's on you to read up and learn.

There are two types of tests you should write: unit tests and integration tests.

Unit tests cover a small fraction of your code. For example, you give a function certain parameters and expect a specific output. If it doesn't happen, it's time to fix that function.

Integration tests check how certain actions behave as a whole. Once the unit tests confirm that each piece works in isolation, it is time to make sure they work together. This becomes extremely important if you plan to add continuous integration (CI).

These two types are the most common and, in my opinion, the most important when working on teams.

Document your code

Taken from Tenor.

You already have a README—why add more documentation? The person landing on your repository knows what the software is about, sees that it works, and wants to add a feature. They clone the repo and jump straight into the code. Now what? They'll bump into methods you implemented that they probably need to reuse or improve.

Well-documented code is good code. I'm not saying you need comments on every function, variable, and if, but it's helpful to add them to most parts. Give a short description of what it does, the parameters it expects, and the output it returns.

Many IDEs (Integrated Development Environments) use these comments to show inline help when a developer calls that method or class.

Method documentation shown in PyCharm.

Document your software

Stephen Colbert. Taken from Tenor.

More documentation? Seriously? Remember that this code belongs to everyone involved; the more you explain how it works, the better. Can you imagine having to personally explain everything to every person interested in your repo? 🤯

You already have a README with a quick summary of your project and well-documented code to help developers use or improve it. So why add more documentation? Because you know exactly how your software works and contributors have some idea, but what about your users? 😳

We often forget about the user. We write code like the best butcher and forget to cook it for our customers. Whenever you buy an appliance it comes with a manual—one part is full of technical specs you probably don't understand, and the other part walks you through simple steps. Software documentation works the same way.

This type of documentation is more descriptive. For end users it varies depending on what your software does. If it's a desktop app, explain how to download, install, and configure it. Highlight the main features and how to use them. If it's a web app, describe how to deploy it so they can have their own instance. These are just a few examples. What it must include are the features and how to make the most of them.

The technical section dives deeper for your contributors. Walk them through installing the required tools and the software itself. Document the common errors that might pop up and how to solve them.

A well-structured piece of software usually has an abstraction layer that shields contributors from tedious, repetitive tasks—like reading a config file without having to check whether it exists or create it. Documenting this is key so contributors don't re-implement something that already exists.

There are plenty of tools that help you write this documentation and even publish it online for anyone to read. As a Pythonista I use Sphinx and Read the Docs.

Test and deploy automatically

Continuous integration and continuous deployment (CI/CD) might not feel essential for contributors, but they keep your repository in shape and prevent unexpected errors from slipping by unnoticed.

With GitHub Actions you can run unit and integration tests on every pull request or on commits to specific branches. That way you know whether the new changes pass all the checks. Imagine your repository becomes popular and you start receiving dozens or even hundreds of pull requests every day. How will you make sure everything still works? When many people contribute to your code, an error will eventually sneak in. Automated tests help keep your code free of bugs when you integrate someone else's work (as long as the tests you wrote earlier are solid 😉).

So many changes also mean new releases, right? Continuous deployment lets you automate the build or deployment of your software every time you cut a release.

GitHub's automation workflows make it possible to run all of these tests and deployments automatically.

Bonus: Talk about your project

Taken from Tenor.

Communication is key. How will potential contributors know your project exists if you don't talk about it?

GitHub helps people discover repositories with tags and relevant metadata, but that's not enough.

About section. You can find it on the right side of your repository.

If you want people to learn about what you've built, you have to tell them—basic logic. Write a short post with an image of what you've done. Share it on your social networks, but don't stop there. Join communities focused on the technologies you used and post it there too. If you have any channel like Telegram, a podcast, or a blog, talk about your project there as well.

Soft skills are what make a developer stand out. Someone who can communicate, work in a team, or handle marketing and copywriting is a major asset for any company. I'll leave it at that. :)

Conclusions

This might feel a bit overwhelming if you don't have any of it yet or you've never done it before. Start with a solid README and add the rest over time. Remember that the most important thing is for people to be able to use the software, which is why I focused so much on documentation. It's how you tell contributors: this is how things are structured, build on top of it and make it better!

I recently open-sourced Threadly, so if you want to contribute here's the frontend repo. Once I add some of the steps I mentioned here, I'll release the API source code 😅 (I know, shame on me).

If you like content like this, join my Telegram channel or send me a message on Twitter.

If this post brought you value, consider returning the favor with a tip on Paylink.