Cover image for New Dev? Job-Hunting? Avoid These GitHub Mistakes!

New Dev? Job-Hunting? Avoid These GitHub Mistakes!

msarit profile image Arit Amana Originally published at arit.dev ・5 min read

Enjoy content similar to this post on Arit, Developer!
Subscribe to Arit's Newsletter
to receive quasi-monthly emails whenever she publishes a new story.

In recent weeks, several developers looking for their first dev job have asked me to review their resumes and/or portfolios, and give them tips on how to improve their profiles. Many of the issues I flagged appeared in most of the profiles I reviewed, so I decided to write this piece with some (unsolicited 😊) advice on how to avoid a flat, one-dimensional GitHub profile as a new software developer. The reality is that the market for new devs is becoming increasingly competitive, on account of more and more coding bootcamps churning out entry-level developers by the month. I think that the time spent crafting a unique, informative job-seeking profile is time well spent. So, onto the mistakes!

Mistake #1 - Stuffing every single app you've built into your GitHub
I think this behavior comes from the belief that: the more apps we have built, the more competent and versatile we appear. However, including every app you have built in your GitHub can have the opposite effect, and cause you to appear unfocused and insecure. Instead, choose only those apps that:

  • Showcase your growth as a developer: To do this, you could include two iterations of one app in your portfolio: the first iteration would contain the rudimentary code you wrote at the start of your learning, and the second would have all the improvements and refactoring you've done since you first built the app. In the README of the improved version, explain the changes you made and why.
  • Represent the fruit of certain struggles you faced while learning: Include apps that you struggled to build, and document these struggles and how you overcame them in the README. These apps give you ample subject matter to discuss during your interviews.
  • Represent your ability to combine several functionalities and cause them to work together: Something I see over and over in new dev portfolios are apps that boast only one main functionality. For example, one app incorporates authentication; another app consumes an API; still another app implements chat between users. I suggest including apps that implement several functionalities that work seamlessly together, as this is more representative of the apps you will work with on the job.
  • Showcase your passion (or was major fun to build): This point is more about being able to exude confidence and authentic emotion while speaking about your apps in interviews. No matter how technically impressive, if an app does not make you want to talk about it and field questions about it, do not include it.

Mistake #2 - Empty, Default or Scanty READMEs
When someone navigates to your GitHub repo, they see a title and a column of folders. Most will scroll down the page to the README section; only to be disappointed by the default GitHub README text or nothing at all. They may never get a sense of the awesome code living within the repo, because your undeveloped README gave a poor first impression. As a job-hunter, you want to make the process of getting to know you as simple and straight-forward as possible. Your README is your opportunity to do just that: to tell a story that will draw the hiring manager in, and make them desire to learn more about you. I think the README for every coding project included in your GitHub should include the following:

  • Rationale for building the app: Nothing ground-breaking or save-the-world-ish is necessary. Just a short explanation for why you chose to spend precious time on this particular app. Maybe it was to teach yourself a certain library. Or create a solution for elderly dog-walkers.
  • List of App's Functionality: A bullet list of what your app does.
  • Problems Encountered & Solutions Implemented: This goes back to the point above about the quality of apps you include in your profile. In my opinion, if building an app was easy, breezy, follow-the-tutorial-prompts, you should exclude it. It is those apps that took a fair amount of effort that showcase your tenacity as a developer, and the README should detail those struggles - just not in whole paragraphs though!
  • Instructions for Deploying the App Locally: This isn't true of most hiring managers, but there are some who like to deploy the apps of candidates locally, try to break it, then come up with questions to ask the candidate. So I recommend having simple steps to reproduce your app in a local environment. Be sure to state any prerequisite operating systems (like MacOS only) or software.

Mistake #3 - Including Apps that aren't Deployed Online
Like I said above, few hiring managers will attempt to deploy your app locally. But most would like to interact with your app and test its functionality. Undeployed apps are cousins to Undeveloped READMEs; by not deploying your app, you again miss that crucial opportunity to draw the interest of hiring managers, and showcase your skills in a dynamic way. So please, deploy every app you include in your GitHub.
-- What if my app is mostly back-end? No problem! Implement a very rudimentary frontend, deploy the app, then explain in the README that you focused solely on backend for the app in question, so the frontend is not intended to represent your skills, but merely to grant access to the backend functionality.

What about Unfinished or Abandoned Apps?
Several devs whose profiles I've reviewed have objected to my advice on including only high-quality apps in their GitHub. "But I'm currently working on several unfinished apps - where do I put them?" Well, there are several ways to distinguish your finished apps which are ready for exhibit, from those still under construction.

  • Pin your apps for exhibit to your GitHub profile: Under "Popular Repositories" on your GitHub profile, click on the "Customize Your Pins" link to the right, then select up to six apps to be displayed. Anyone landing on your GitHub profile will see these apps upfront.
  • Prefix unfinished apps: Add an "In Progress" prefix or flag to your unfinished apps. This approach indicates which apps are still being built (and hence, should be ignored or taken with a grain of salt).

NOTE: I initially included the tip "Have 2 GitHub accounts; use one for the apps (finished or unfinished) that you wish to showcase" but upon reflecting on several objections in the comments, I've decided to pull that tip out of the article.

Your choice of portfolio apps should reflect the story you wish to tell and the competence you wish to reflect as a developer, not just that you have this Swiss-army knife of skills. The goal is to convince hiring managers that you are an asset to any dev team; choose those apps that demonstrate your ability to wireframe tech-based solutions at a high-level, locate and incorporate tech solutions efficiently, and work in a self-directed, self-motivated manner.

Thanks for reading! 🤗

Enjoy content similar to this post on Arit, Developer!
Subscribe to Arit's Newsletter
to receive quasi-monthly emails whenever she publishes a new story.

Posted on Oct 29 '19 by:

msarit profile

Arit Amana


Former Public Health Analyst. Coding Bootcamp Grad. Mentor to women (especially moms) who are transitioning to tech careers.


markdown guide

I think treating Github profile as a portfolio is a mistake, made both by developers and by hiring staff. It's not a portfolio - it a set of repositories. If you want a portfolio, build one and link interesting projects (with description etc.) in it.


Thanks for your comment, Paweł. I don't think that GitHub should be one's ONLY portfolio; however, it is an important part of your developer persona, and this article presents some tips for improving that one aspect of your entire profile. That's all. Please tell where my piece sends the message that GitHub is a dev's ONLY portfolio, and I will amend accordingly. Thanks again!


"important part of your developer persona" - yes, totally agree with that! But the very word "portfolio" sounds to me like something done to impress, polished in every aspect, showing only selected best pieces. Perhaps that's just our difference in understanding that term.

Github profile, to me, is more like a workbench you decide to put publicly for everyone to see. Sure, there will be some people saying "your workbench is untidy" and dismissing you for that. On the other hand, tidy workbench means it only for show and nothing real is happening there. My experience is that when I see a polished, tidy Github profile, I usually just skip it. Dirty profiles with many forks, experiments, unfinished tales - that's what I find interesting (as an interviewer).

BUT. Different contexts and different measures. I believe there are situations when a polished profile is worthy thing - in those cases your tips are great. I don't mean to sound condescending or anything - I just wonder if we don't put too much pressure on how the Github profile should look.

But the very word "portfolio" sounds to me like something done to impress, polished in every aspect, showing only selected best pieces.

Perhaps it is the use of the word "portfolio" that is throwing people off lol! for me, a portfolio is just that: a collection of your work meant to indicate your expertise (or lack thereof). My tips come from the understanding that, as our GitHub repos represent our code "portfolio", it makes sense to make the most of the first impression that that portfolio gives.

I believe there are situations when a polished profile is worthy thing

I've heard from dozens of developers (across all levels) how a well-organized GitHub made a positive impression on hiring managers. I'm one of them - I had more than one hiring manager comment on how refreshing it was to read my READMEs and get a strong sense of what my apps were about before even test-driving them. That said, I recognize that my tips are certainly not applicable in all situations.

I just wonder if we don't put too much pressure on how the Github profile should look

Now this is another discussion entirely lol, one I'm willing to have of course. Thanks!


Have two GitHub accounts

I find that a dishonest practice. I know how the sausage gets made, when I enter a butcher which is open for business, and it's squeaky clean, I know something is amiss.

Failing is part software development, it is how you get experience and grow. I expect to see failed/unfinished projects. Not finishing personal projects is not a bad thing. You should be able to explain why you abandoned a personal project, generally this would be something like "I lost interest because I found a some other technology I was more interested in."

Of course if all you have to show is projects which you only spend a few days on before abandoning them it doesn't paint a good picture.


thanks for your comment Michiel! I'll amend that paragraph soon to reflect the fact that I do not mean that one should misrepresent themselves, or project an image of perfection. It's simply an option; if you're like me and have dozens of repos, the work you'd like to be judged on can get lost in the mix. Thanks again!


if you're like me and have dozens of repos, the work you'd like to be judged on can get lost in the mix.

That is a good point. But wouldn't it then be better to create a personal GitHub page where you highlight your favorite personal repos, for resumé sake.


I think some hiring managers also just look at the github activity, in which case having a clean account doesn't really help.


This makes sense to me too; alright I think my second GitHub account tip has made enough waves to be revised or removed lol! Thanks for your comment!


GitHub has been an important "demo ground" for me when interviewing.

Thanks for your tip about pinning repositories on the profile page -- my GitHub account isn't for show: it's for getting stuff done! But in there are some repos which do demonstrate my abilities and accomplishments, so pinning those makes sense (:


Awesome - I'm glad you found some tips helpful! Best of luck on your continued developer journey! 😄


As someone who has interviewed software engineers and security engineers I will tell you there is a common theme: they don't have GitHub profiles. I'm not kidding, about 10% of applicants had a website, blog, or GitHub profile to share. If you even had a BLANK GitHub profile it made you stand out. Have ANYTHING on your GitHub profile.


WOW! Thanks so much for sharing! That's crazy, and underlines again my motivation for this piece.


These are helpful tips for anyone. I'll use these as a guide the next time I revamp my Github presence.


You're welcome Shannon! Thanks for reading!


Github is the atelier of a developer

I honestly don't think that github is a good place to show only your best work. If you are going to check my github, you will see every side-project I've worked on. It's not meant to be a portfolio, but a work table.
If you are only showing the better, polished, clean, and sometimes modified stuff, how do you expect someone to know what are you qualities, and flaws? Having two github accounts is also not really a good idea, for the same reasons. Considering the amount of possibilities to create an actual page to show your work (github pages, netlify, etc..), masking your profile like that doesn't sound really good. In my opinion is not even honest.

Making an analogy, I would say that the github (or gitlab, bitbucket,etc...) is the atelier of the developer. When you see an atelier of a sculptor, you expect to have residues from the material used (like mud, wood,etc) ,tools on the table, and other unfinished works on the corners. The same applies to our github. Of course, our pinned repositories are the ones we are proud of, but our work, our side projects, should be there as well


Thanks for your comments.


Github allows for private and public repos. I do my self-study and learning projects privately. If I have something I want to share, I can make the repo public.


Excellent point! Thanks for sharing!


I really really like the points about the README file. I currently am in the middle of building a 30 project project on Github and I am forgetting what features I've built into them so that I can showcase the skills I have.

Thanks and bookmarked!


Great tips! You can also use a gitconnected.com profile to display the projects that you want to feature for a recruiter / hiring manager without needing to worry about the unfinished/undeployed ones.


I did not know this! Thanks for sharing! I may update my article 😄