How to design a profile on GitHub

This article is about how new developers can set up their GitHub profile so that it becomes an added advantage in the interview. The article will be useful primarily for beginners, because it is more difficult for them to find a job than others. Experienced specialists, too, I hope, will find valuable considerations and practices in this material.

I have been managing product creation processes for over 15 years, from hypotheses to sustainable sales. For the past two years, together with fellow kottans, I have been helping beginners and switchers acquire new technical skills in development, develop soft skills and find their first job in IT. I often see people have problems with the presentation of their skills and personal projects, in particular the profile and repositories on GitHub, so I decided to write this material.

Let’s agree on the context right away: we will talk about setting up a profile on GitHub to find a job.

Is it necessary

Most often, a candidate for a developer position is expected to have a certain level of technical knowledge. It is especially difficult for beginners: there is little practice, experience in passing technical interviews is also not enough or not at all. And also pre-screening… Candidate code written before the interview can become a competitive advantage. Test tasks are given not only to test the ability to write algorithms and operate with data structures, but also to see approaches to solving a problem, project structure and code. Any code available at the pre-screening stage may be subject to review by the interviewers before the first meeting. And who knows, maybe you will be given fewer test items or even do without them. And tests are always stressful, affecting the quality of work.

There is hardly a better place to store code than GitHub. And even a small portfolio of neat and expressive code can be the main trump card of a candidate in the fight against competitors for a vacancy.

There are different views on open project portfolios on cloud VCS (GitHub, GitLab and the like). Many experienced developers believe that no one is looking at the profile (see the simple solution). For some team and tech leads, seeing the code style and how code is organized in a project (especially for a junior candidate) is better than hearing 1,000 words in an interview. The correct design of the profile and two or three of the most indicative repositories on GitHub will help you beat the competition. And when several equal candidates remain at the end of the interview cycle, then every bit of information can be decisive – including projects on GitHub.

In any case, if you already indicate a link to a GitHub profile in your resume, then it definitely makes sense to help the reviewer see the most important thing.

Of course, the first thing the reviewer will see is the title page of the profile, from which it needs to be directed to a specific project or projects. Everything here should be informative and convenient.

If the profile is empty, a logical question arises: why is the link to the GitHub profile added to the resume and why is the list of projects empty? The answer “Well, if necessary, I will add it” is bad.

Let’s start with projects.

What to show if there is nothing to show

Nobody (sic!) expects to see a unique project with 100500 lines of code. Evaluation, most likely, will be the level of proficiency in design patterns, code style, the ability to write minimal documentation, and skills in working with Git. Why is this all important? Because it’s about communication. This is what will be expected of the employee, in addition to writing the actual code. Code is written primarily for other people.

Of course, they can also assess the level of technology proficiency. It’s one thing to read “CSS3 Medium” on a resume or hear the answer to the question “What can you do in JavaScript?”. It is quite another thing to see in the repository a well-read code that reflects real technical skills.

A disclaimer for pedants: it is clear that one can deceive both there and there. But this article is not about this class of problems.

Choose two or three projects that best reflect your skills. Training ones are also good (quickly finished the unfinished ones). Or add one or two simple games like tic-tac-toe, Frogger or Memory Game. All beginners do something like this, but not everyone completes and shows. Do not look for originality – this is all for the sake of demonstrating skills and abilities. Demos don’t have to be complex, with animations, embedded video, and a million visual effects. One chip is enough.

Here’s a great example of front-end student-turned-MacPaw developer Mary Fedirko doing a weather radio (press the ON button). In this project, she showed a creative approach not only to writing “the next JS framework”, but also to the design and external presentation in general. A non-standard type of educational project is both an additional motivation in the process of implementation (to make such interfaces much more interesting), and an increase in the likelihood that an employer will pay attention to such a project.

It would be great if someone could review your code.

Some developers are advised to disclose participation in open source projects in the resume. And for this you need to participate in such projects 🙂 In fact, it is not very difficult and you can even find materials and support in this process.

Another source of projects is hackathons. Online, offline, local/international – take your pick. Dozens of them are held monthly. In addition, the indication of hackathons and meetups in the resume is a clear indicator of interest in the profession.

One more piece of advice: Better learning raps than zero raps. Other things being equal, a candidate with even “primitive” designs outperforms a candidate with no public traces of activity. Repositories can be deleted, archived and made private – so the profile will become more and more professional over time.

Making a repository

The purpose of the design of the repository is to show the product “face”. In this context, those who draw up the project in the style of “figure out how to run my application to see how it works” lose out. Because all this may be obvious to the author, but not to an outside observer.

In the user profile, it is possible to pin up to 6 projects. Choose (or create) the ones that best showcase your skills, and get to designing them. This is not difficult.

Brief description and link to publication
At the very top of the project page there is a place for a brief description and a link to a working deployed version. For a frontend with a link, it’s easier, of course. If your project can be published – do it, at least on GitHub pages. Even an automatically generated page from the documentation is already something. Firstly, it is at least somehow indexed by Google, and secondly, it allows you to develop the habit of designing a project in full.

Description, by the way, forms the content of the <title> tag of the project page, if you know what I mean.

Documentation

Most often README.md contains only one line: # project-name.

What should be in README.md:

What is the project about? For example: “A movies database web application”, “Rick and Morty universe REST server”.
Why this project? For example: “I mastered CSS animations, CSS Grid, CSS Flexbox” (points, of course, should be written as separate bullet points).
Link to the demo (yes, yes, once again repeat what is already in the description – overcommunication is not a sin).
Instructions for building and running the project. That’s all git clone … , yarn build … and so on – as in adult projects.
The structure of the project, the architecture of the application, the API – this also shows the skills needed by the developer.
Write it all in markdown syntax. So we demonstrate the possession of another useful skill.

The purpose of this is not only to give the reader a good idea about the project, but also to show the attitude towards documentation (it will be possible to dislike writing documentation later) and basic documentation preparation skills. See, for example, a tutorial project using The Movie Database API.

By the way, making a website out of such documentation can be relevant for non-front-end projects – documentation without unnecessary GitHub interface elements is read better. It’s pretty simple: you need to enable publishing in the settings.

Advanced Techniques

Screenshots, screencasts
If the application has a human interface, the screenshots in the documentation will add points.

A screencast in the form of a GIF will make the demo even more visual. Example: task description in a frontend course. It is better to host a gif outside of GitHub, for example, on imgur.

How to make such a gif? For example, oCam for Windows. You can record a screencast using QuickTime for Mac or Windows 10 built-in tools (Win+G) and then convert using MOV to GIF or MP4 to GIF.

Asciinema works well for writing terminal work.

Topics

For the future: topics help the project appear in search queries. What keywords to enter? Start with the technologies used in the project: JavaScript, ReactJS, Python, Java, C#, Laravel, PHP, REST, MongoDB, Node, PostgreSQL, SPA, web app, AMP, CSS, HTML… Add two or three keywords about the project: game, casual game, database, movies, weather, demo, educational, tutorial… GitHub will suggest something else from its list.

The code

Logically, this section should be higher. But this is perhaps the most difficult part for beginners, so I left it for last.

Code style

Did we already say that code is written for other people? Again, code is written for other people. This means that the code must be readable. Compliance with the code style adopted in your technology stack, adequate naming of variables, classes, functions, modules and files – all this is important in work. If a person does not follow this even in his smallest projects, where he is a king and a god, one can hardly expect that he will do it well in others. There is a chance, of course, but from experience it is very low.

So “comb” the code that you plan to show. Linters will help you (at the same time learn how to configure if you don’t already know how). You can, without hesitation, take pre-configured projects – Open Source. For example, ESLInt-Prettier-Husky boilerplate for front-end JS or EodData CLient (Python, Aleksey Ivanov). For your stack, you’ll have to look around or ask someone around.

Commits

Commit comments are also written for other people. Comments like “added file”, “fixed”, “add code” and similar (careful, bad advice!) speak of insufficiently well-developed presentation skills and dislike for people who will read your code. It’s time to get the right skill. And it’s better to suffer a little over the texts of commits in educational or pet projects than to listen to grouchy remarks from senior colleagues or not to find anyone willing to make a code review at all.

Here is one example of a readable commit history: frontend project lvl1 by Sergey Shramko.

A simple solution

In order not to deal with all of the above, you can simply never admit to anyone that you have a profile on GitHub. No material – nothing to criticize.

They even say that it’s all useless: why GitHub won’t help hire a developer / Sudo Null IT News

The choice is yours.

Total

A GitHub profile works and helps – when it exists. Making it neat means taking care of those who will study it in the pre-screening and interview process, and, therefore, of yourself as a competitive candidate.

Testimonies of “eyewitnesses” from among my acquaintances, novice developers:

Eugene, Front-end Developer: “I was asked about the most interesting project: what does it do, why is it so, logic and module connections. Another project was also opened and questions were also asked about it. I’ve been employed for a couple of months now. In my opinion, what worked: 1. A lot of test tasks from other social services, some of which I published on github; 2. Own atypical and working micro-projects.

Lena, Front-end Developer: “They asked questions about my projects at several interviews. We looked at the portfolio. At one, they asked for comments on the most interesting project from the examples on github.

Have you ever looked at your portfolio? Did your portfolio help in your job search?