Introduction

Companies ask for a GitHub profile. Recruiters ask for a GitHub profile. The question “Do you contribute to open-source?” is now one of the most common questions asked in phone screens.

If people want a GitHub, we shall give them a GitHub. This article will explain how to present a GitHub project for use in a resume.

The given advice can be read from two point of views. As a candidate, it is what to write to introduce and present a software (not necessary on GitHub). As an interviewer (or a fellow developer), it is what to look for to judge the experience of the developer(s) and the quality of a software.

Link to a specific project

Put a link to your GitHub in your resume and every application forms you have to fill.

That link must send directly to a project. Never link to the root of your GitHub profile, it doesn’t show anything useful and it’s hard to navigate from there.

It means that you must have ONE project to show. A single demonstration project is enough, don’t need more.

This project will be the “landing page” in web buzzword. This is the first page the employer will see. They will rarely go past it (and they shouldn’t have to) so the page should be a good enough by itself. If they go past it, it’s only because the page grabbed their interests and they wanted to see more.

We’ll write the project page to give a good first impression and show off skills as a software engineer.

Project Structure

A software project can be judged in 5 seconds by looking at the directory structure.

An inexperienced developer is easy to spot. His project doesn’t have any structure. Files are either in unpredictable places or all in the top directory.

There is one project structure to rule them all. There MUST be separate directories for source, test, libraries, compiled binaries, etc…

Whether the naming convention will be “doc” or “docs” is an unimportant detail. For example, here are Simple Folder Structure Conventions for GitHub projects:

.
├── build                   # Compiled files (alternatively `dist`)
├── docs                    # Documentation files (alternatively `doc`)
├── src                     # Source files (alternatively `lib` or `app`)
├── test                    # Automated tests (alternatively `spec` or `tests`)
├── tools                   # Tools and utilities
├── LICENSE
└── README.md

Have a README

Have a README to:

• Describe the purpose of the project
• Screenshots/videos
• Usage
• Link to the installer/webpage
• …

Have screenshots in the readme

A picture is worth a thousand words.

People are not going to install the application just to see it. Give them screenshots.

Have videos in the readme

A picture is worth a thousand words. A video is worth a thousand pictures.

There is nothing better than a video when it comes to giving a demonstration or showing off an application.

Note: GitHub does not allow to embed video files in the readme, use animated gif instead.

Link to a website or an installer

Link to the site if it’s a web application project. Of course, a web application should be running somewhere and publicly accessible, that’s the point of web applications.

Link to the installer if it’s a desktop application project. It’s unlikely that the user will install it but that looks professional, that’s how desktop applications are distributed after all.

Integrate GitHub tools

GitHub has a rich ecosystem of free tools for building, packaging, testing and much more. All these tools are mandatory for professional software development.

It used to be hell to setup the tooling but now everything is readily available for free through GitHub and the setup is dead simple. There is no excuse to not use the tooling.

This one is a sample C++ project for a Connect Four. From left to right:

1. Build on Linux (Travis CI)
2. Build on Windows (AppVeyor)
3. Unit tests and coverage analysis (Coveralls)

What about the source code?

“Nobody cares about your code. It was quite a shocking moment when I learned this in my programming career. I would take great care in polishing my code only to find out nobody actually cares. It’s not the code that counts, it’s the product. ” — Source

A paragraph to explain the purpose of the application is 10 times faster than guessing it. A quick start video of an [non-trivial] application is 100 times faster than figuring it out. A design diagram is 1000 times faster than reverse engineering the application. All of these could be achieved by reading the source code, at the cost of orders of magnitude more time and headache. It’s extremely slow and difficult to read code (or should we say to decode code). It should only ever be a last resort.

Lesson #1: Noone cares about your source code. Noone is gonna read it.

Lesson #2: Don’t expect people to read it. Don’t force them to.

What if I don’t have big projects to show?

Good. Smaller projects are easier to show, easier to explain and easier to understand for the interviewer. For instance, everyone can grasp a good old Connect Four.

It is not a trivial project despite what it looks like at first. Write a decent UI, put some colors, allow a two players option, add a “hint” to show the best next move, add an AI to play against.

While the game is conceptually simple there is a lot of work to turn it into a good and polished software. That leaves plenty of depth to talk about in a face-to-face interview.

Did you know that the first player in a connect four game always wins? [if playing perfectly] Did you know that the second player can always draw the game, if the first player doesn’t take the middle position as his first move?

Source: A Knowledge-based Approach of Connect-Four, The Game is Solved: White Wins, Victor Allis

Do interviewers really look at GitHub?

As a matter of fact: No, they don’t.

We’ve done the tests. Here are the statistics after sending a bunch of resumes. The 3 views are from myself, I accessed the project while writing this article, without being authenticated to GitHub. Oops, my bad.

From personal experience from the last time I looked for a job. After a dozen of phone interviews (1 dev per call) and a couple of on-sites (4 to 7 devs per on-site), there was only 1 visit to my profile.

Conclusion: Noone cares about GitHub. Noone is gonna read it. Everyone is gonna ask for it nonetheless, cause it’s hype.

Bonus: Since noone will check the link they’re given, you too can refuse to participate in the GitHub masquerade by answer all GitHub request with the ultimate hello world repository. This is a repository of hello world in hundreds of languages.

Cheat Sheet

1. Structure the project
2. Have a README
3. Write a paragraph to explain the purpose of the project
4. Put screenshots and videos
5. Distribute an installer (desktop app) or give the website (web app)
6. Integrate development tools (CI, unit test, packager, etc…)

That’s good practices for software projects. It’s not limited to GitHub.