How to Improve Our GitHub? How to Prepare a Profile? How to Write a README?

How to Improve Our GitHub? How to Prepare a Profile? How to Write a README?

Hello everyone! In this article, I will cover how to make our GitHub/GitLab profiles, repositories, and README files more effective and professional. Additionally, I’ll explain why these elements are so important. Instead of focusing on questions like What is GitHub? / What is GitLab?, we’ll dive into often-overlooked but globally significant details.

Photo by Roman Synkevych on Unsplash

What is GitHub? What is GitLab?

I won’t go into these topics in detail, but for those who are curious, here are some excellent resources to check out:

• What is Git, GitHub, GitLab? Git Commands — Tuğçe Akın

• What is Git? GitHub Usage and Basic Commands — İrem Ateş

Why Are GitHub or GitLab Profiles Important?

The answer is straightforward: Your profile is your digital CV in the software world. Whether you’re applying for a corporate position or working as a freelancer, your CV or portfolio is one of the most critical tools to showcase your skills and experience. In the software industry, the most effective form of this portfolio is your GitHub or GitLab profile.

Moreover, GitHub’s ability to connect you with job opportunities globally makes the content of your profile even more crucial. Thus, not only should your profile be well-organized and professional, but the repositories you direct people to should also be structured, clear, and user-friendly. Your profile and repositories are the most powerful tools to represent you and reflect your skills.

So, How Do You Do This?

If your GitHub profile looks similar to the example below, you probably haven’t created a README.md file or a repository with your username. Let’s create a repository using your GitHub username together! 😊

You can proceed just like creating a normal repository. Enter your GitHub username in the repository name field. GitHub will automatically recognize this as a special profile repository. Then, select Add a README file and create the repository.

Repository Creation Stage

Repository View

Profile View

After creating the repository, your repository will look like the one on the left in the image, and your profile will resemble the one on the right.

Now, it’s time to fill out and enhance your profile README. But how do you do it? Coming up with something from scratch might seem difficult, but there are tools to make this process easier. 😎

How Can I Improve My GitHub Profile?

There are plenty of tools to help with this, so there’s no need to worry. Even if you think your profile doesn’t look great right now, there are websites and ideas to guide you toward improvement. Here are a few tools you can use:

1. GitHub Profile README Generator: This is one of the simplest and most well-known tools. Created by Rahuldkjain, this excellent open-source project helps you design your profile by selecting a few options and filling out basic information. Initially, it worked with standard templates, but now it even allows you to integrate your Medium or Dev.to posts automatically.

2. Profilinator: Developed by Rishav, this tool lets you modify styles and layouts via a simple editor. For example, you can divide your page into three sections. It also supports automatic integration of Medium and Dev.to posts.

3. GPRM: Unlike Rahul’s tool, this one offers easier customization of styles and features, helping you create a unique design language for your profile.

If you prefer not to use a tool and want to design it yourself:

Awesome GitHub Profile

• Awesome GitHub Profile: This platform showcases various developer profiles, allowing you to explore different styles and adapt them to your own.

Why Are GitHub Repositories Important?

Repositories play a crucial role in showcasing the technologies, projects, and even small Proof of Concept (PoC) work you’ve done. They demonstrate your knowledge, coding quality, structural skills, and at least your familiarity with a subject. For instance:

• In a job interview, saying, “I know Framework A” is very different from saying, “I have several projects using Framework A.” It shows that you’ve gained hands-on experience.

• Repositories also highlight your adherence to standards. Most companies, regardless of their level, have some development standards that you’ll need to follow. For example:

• Writing meaningful commit messages following the Conventional Commitsstructure.

• Using Semantic Versioning for version control.

How Can We Improve the Look of Our GitHub Repositories?

One of the most important elements for making a good impression with a project is the README file. A well-crafted README makes it easier to understand and use your project. The following headings serve as a guide to making your README more effective:

• Project Name: This represents the identity of your project and creates the first impression. Choose a short and clear title that defines your project. For example, “Weather Forecast Application.”

• Project Purpose: Briefly explain what your project does, the problem it solves, or the need it fulfills. For instance, “This project aims to provide users with real-time weather information. It offers city-based forecasts through a simple and user-friendly interface.”

• Project Features: List the main features of your project. This section helps users understand what your project offers:
  

- City-based weather forecasts
- Real-time updates
- User-friendly interface

• Setup Instructions: Provide a step-by-step guide on how to set up and run your project. Create a simple manual suitable for users with varying technical expertise.

1. Clone the repository:
  `git clone https://github.com/username/project-name.git`
2. Install dependencies:
  `npm install`
3. Run the application:
  `npm run dev`

• Usage Guide: Explain how to use your project. In this section, you can share example screenshots or commands. For instance: “You can view the weather by selecting a city from the homepage.”

• Contributing: Explain how users can contribute to your project. Provide a guide to help users get involved in the development.

  • 🛠 Fork the repository.
  • Make changes.
  • Submit a pull request.

• License: Specify the license for your project. This clarifies how users can use and modify your project. For example: “This project is licensed under the MIT License. For more information, please refer to the LICENSE file.”

A typical README file is structured around 7–8 main sections, though the number of sections may vary depending on the level of detail you want to include in your project. Even if you don’t have Markdown knowledge, you can use the following tools to make your repositories more clear and visually appealing:

• For those who want simplicity: If you prefer to quickly create a structure with just a few clicks, the CLI-based Readme MD Generator is perfect for you! This tool helps you fill in basic details to generate a README file in no time.

• For drag-and-drop users: If you’re looking for a more visual and practical solution, readme.so might be exactly what you need. It allows you to update your information and create a sleek README in minutes.

• For those who like to do it all themselves: If you’re more of a “hands-on” person who prefers to write everything from scratch, makeareadme.com is an ideal resource. It not only explains the importance of a READMEbut also provides an editor to assist in the writing process.

• For inspiration from other projects: If you’re curious about how other developers approach their READMEs, Awesome README is a great place to start. You can explore examples from various projects, including NASA’s OGMA project, and draw inspiration for your own.

How to Ensure Simplicity and Organization in Your GitHub Repositories?

Having a well-organized and aesthetically pleasing GitHub repository not only enhances its visual appeal but also makes it easier for others to understand and use your project. Here’s a step-by-step guide to achieving simplicity and organization in your repositories:

1. Edit Repository Details

As shown in Images 1–2, you can edit your repository details by navigating to the “Settings” tab at the top of the page and filling in the necessary fields.

Actions:

• Description: Write a short sentence explaining the purpose of your project. (e.g., “Weather Forecast Application”).

• Website: Add a link to your project’s demo or documentation if available.

• Topics: Include relevant categories for your project (e.g., vue3, gpt-4) to improve visibility in search results.

Why Is This Important?
These details help users visiting your project page quickly understand its purpose. Additionally, a well-crafted description enhances your repository’s discoverability on search engines.

Edit Repository Details

Edit Repository Details Screen 2

2. Disable Unnecessary Features

If your project doesn’t use Releases, Packages, or Deployments, you can disable these features (as shown in Images 1–2).

Actions:

• Go to the “Edit repository details” menu and check or uncheck the relevant boxes to disable unnecessary features.

Why Is This Important?
Unused or empty sections can make your repository look cluttered. Keeping only actively used features visible adds simplicity and professionalism to your project.

3. Customize Wiki, Issues, and Projects Settings

As shown in Images 3 and 4, you can enable or disable Wiki, Issues, and Projects based on your project’s requirements.

Actions:

• Wiki: Keep this open if you need a space for project documentation. Restrict editing to collaborators by enabling the “Restrict editing to collaborators only” option.

• Issues: Enable this feature to allow contributions and bug tracking. You can also add an Issue Template for structured feedback.

• Projects: Use this section to manage project-specific tasks and timelines. Enable it if task management within the repository is necessary.

Why Is This Important?
Managing these features according to your project’s needs keeps the repository organized and focused. Disabling unused features prevents unnecessary clutter and enhances the repository’s usability.

Screen-3

Screen-4

4. Fill in Required Fields

Empty or missing details in your repository’s About section (e.g., Description, Topics) can make the repository appear incomplete and unappealing.

Actions:

• Fill in all required fields.

• Use a description and tags that align with your project to achieve a professional appearance.

Why Is This Important?
Incomplete information makes it harder for users to understand your project and can make the repository seem amateurish.

5. Language Usage and Visuals

The Languages section in your repository reflects the programming languages used, giving users insights into your code structure. Additionally, enhancing your README file with effective visuals can make your project more appealing.

Actions:

• Add screenshots or diagrams in the README file to explain the project’s structure and usage.

• Include code snippets with usage instructions to provide clear guidance.

Why Is This Important?
Both textual and visual explanations help users quickly grasp the project and encourage contributions.

6. Conclusion: A More Unique and Streamlined Repository

By following these steps, you can simplify and refine your GitHub repository, making it more professional and user-friendly. A well-organized and up-to-date project page is crucial for users looking to evaluate the quality and relevance of your project. Simplicity and functionality not only attract users but also motivate potential contributors.

A polished repository is the most effective way to showcase your project and engage the community!

Remember, a well-designed repository is the most effective way to present your project and capture the community’s interest! — ChatGPT

In this article, I focused on the importance of GitHub/GitLab profiles and README files, sharing key points and tools to help you improve them.

If you have any questions or suggestions, feel free to reach out to me via my LinkedIn profile. You can also find me on Bento.me/eralpozcanor eralpozcan.dev. 🤖

Don’t forget to follow me on GitHub and drop your GitHub profiles in the comments 🎁

See you in the next article! 📩