How to present your projects

Understand how others see your GitHub Repos

I don't know about you, but I don't care about the generic create-react-app project that GitHub user "space_bunny_3510" built.

Face it. Whoever checks your repo will spare you a minimal amount of time. They don't care. Why would they?

Make them care

Seize their attention, before they lose interest.

The very first thing you see in a GitHub repo is the README file. That is our prime target for our attention-seizing scheme. You should also make it trivial to find relevant information.

The README file

I suppose your main audience is potential recruiters. So you should think about what they want to see. That is, the kind of thing you can offer the people that may want to hire you. You should also think about what they need to see so that they can make a decision.

I have a set of questions that will guide me in writing my READMEs

• How I worked on this.
  • You could screenshots of your design or links to a Figma file. Or anything else that showcases how you approached this project.
• How to navigate this project.
  • A summary of how the folder structure is set up.
• Why did I build the project this way?
  • Here you can showcase your critical thinking. Your choices, and your awareness of the different alternatives for tackling this type of project.
• If I had more time I would change this...
  • Show that you are aware of your shortcomings and that you can self-reflect about how to keep growing with every project you work on.
• What did I learn?
  • List all the new skills you gained! You can also show that you are willing and eager to tackle projects that will require you to learn new stuff
• Others
  • I would add a link for any relevant blog posts I wrote while building this project :)

A concise and relevant description is nice too.

Git commit messages

I'd bet seeing a messy commit history will raise some serious red flags. A small set of changes can drastically improve your commit game!

Every commit should be atomic. That means, a single chunk of changes or a single feature or added file per commit. Generally, atomic commits make a good heuristic. There is not much use in trying to formally define what "atomic" may mean in this context.

Let's keep it pragmatic! One useful heuristic I use is asking "can I describe this commit in less than 70 characters?" That is because the commit message should be no longer than 70 or so characters.

Commit messages should start with a verb in the imperative form. For example "Fix error when reloading the page". Here is another heuristic for writing commit messages: "If applied, this commit will ". You see that it only makes sense if the message starts with an imperative verb.

A concrete example: Frontend Mentor challenges

Let's see how I try to apply these principles. I'll share a Frontend Mentor challenge I did the last December. The only new change I will make today is adding a README file, according to the guidelines above.

You can check the repo for the project. And you can play with it here https://jorchrl.github.io/spaceTourism-website/. It is hosted on GitHub pages.

You can check both the commit messages and the README on the repo. But I'll share screenshots here anyways.

Here's the commit history:

And here is the README:

I would advise you to keep this as concise as possible.

Nobody enjoys a wall of text.

Epilogue

I am trying to write something everyday. I figured that it would be easier than working in more highly-polished posts. Well, I did write something today. The problem is that I spent the whole day!

I hope you find this helpful, or at least entertaining. Help me grow by leaving some feedback for me!

See you tomorrow! (I hope)