GitHub Mentoring

Over the course of 2020 and 2021 thus far I have mentored seven up and coming software developers from several communities: Bellingham Codes, Tech404 and Linkedin. I mentored them to optimize their GitHub account for prospective employers/recruiters/OSS opportunities. I spent 20-40mins over Zoom with each of them and learned a lot myself about what it is like getting started in the industry today. As of writing this, I am aware that one person has landed a job and one has advanced in interview stages aided by their GitHub.

This blog is a synthesis of what I was taught at my General Assembly Bootcamp in 2016, my lived experience as a developer the last four years and the experience of mentoring up and coming developers. It follows a few stages and is intended for someone starting out in the industry.

Spoiler: It is not all about the contribution graph. It is about context and usability.

First… I am biased towards GitHub and I think it can be quite important. For some people, especially experienced programmers who were around before Git and GitHub, it may be completely unnecessary and frustrating that people now think it is important. My bias comes from my (in)experience and naive wisdom: my GitHub profile was essential in getting my first full time remote developer job that changed my life.

I applied for quite a few jobs and worked with several recruitment agencies. When I got an interview for a full time remote web developer position I was asked about stuff on my GitHub account.

I linked to my GitHub in my PDF resume. In the interview I answered questions and talked about my projects. I was particularly asked about the project FreeSpot and then… I got the job. My new workplace seemed reasonably interested in my law degree and other things. However, if I did not have a GitHub account or if it was not up to scratch I don’t know if I would have gotten the job especially as I was interviewed remotely.

I became fascinated with GitHub and it stuck with me after I gained my first software job. I don’t have a huge amount of contributions like some people do: my contribution graph is quite barren. This is a common thing for many people who get a job but don’t work in open source: most of our code is proprietary. Some developers argue they don’t need their GitHub anymore once they get a job except maybe using it for hobby stuff if they have any time for that outside of work (and many don’t). For many people if they work on weekends they work to get paid… not make side projects on GitHub.

Despite the apparent lack of necessity of GitHub after I got “the job” I still worked to curate a selection of repositories, forks, stars and ReadMe’s. I think that these cumulatively say something about me for anyone that might be interested for a future opportunity whether work or non-work related.

I love mentoring about GitHub mainly because it is actually… kind of easy. Learning Git is the big hurdle. Once you have the basics of Git down the essence of GitHub is really about learning some Markdown for writing ReadMe’s: the rest is following an intuitive UI. You need code to put on your profile… but it doesn’t even have to be your own original code. Sometimes it is even better if the code on your GitHub account is not original: copying and remixing is the bread and butter of most developers lives. I discuss below that some people looking at your profile will understand that.

Mostly it is just encouragement. Do stuff! . A lot of the things we will see are quite easy to do from the UI of the site to breathe life into your projects. You can have a look at my imperfect github… I am willing to put it out there as an imperfect profile but one that got me a job.

My advice in summary:

  • Empathize with the range of people who might view your GitHub i.e Hiring Managers, Recruiters and Developers. They often have constraints from being able to look closely at your code. You have a limited time window to keep their attention.

  • Describe who you want to be in your bio, even if you feel you are not there yet.

  • Use a good image as your avatar.

  • More is better basically (but don’t spam it).

  • Create a personal profile ReadMe

  • Re-brand school work and tutorials as personalized content

  • Have 4-6 Pinned repositories with fully detailed ReadMe

  • Add Topics to your repositories

  • Visit every few days and star or fork a cool project that catches your eye

  • The Gold Standard: OSS contributions

Empathize with the range of people who might view your GitHub… it might be hard at first.

Your projects and code might mean a lot to you. You may have poured a great deal of time into your repositories over months with the hope of using them towards getting a job. You may also have feelings of insecurity that whatever you put up is not polished enough: many people don’t have their code/stuff on a place like GitHub at all because of these feelings.

Let us exercise our empathy muscles. The person viewing your GitHub account who might decide whether or not you get an interview or advance to the next stage could potentially be:

  • Tired and pressured from viewing dozens of job applicants in a tight timeframe and unable to really appreciate nuance or a lot of detail. This was emphasized to me by quite a few people. I don’t keep count but easily mentioned by at least six that have been involved in hiring at some stage.

    • What do we do? We make it easy for them by following some of the advice in this blog
  • Potentially less technical people such as a recruiter who are highly dependent on finding keywords in your GitHub to tick the check boxes of what they are looking for.

    • What do we do? We make make it obvious for them. We use bold and consistent keywords. We use topics in our repos to make it even easier.
  • Unable or unwilling to actually run your code. Some people are reliant on the quality of your ReadMe’s and other indicators of your coding ability to make a interim decision about you: many people don’t have the luxury of cloning and building a project from a repository particularly on work machines.

    • What do we do? We include easily accessible human readable code such as in a /src directory in the top level of the project and make that the forefront of our projects. Don’t obfuscate or minify everything!. We include a detailed ReadMe with media and information to support the viewer who cant run the project or read too deeply.
  • Instinctively judgmental based on perceptions of professionalism or that you are “just another boot camp grad” or otherwise. You can’t fight totally misguided assumptions - possibly you don’t want to work for someone where such assumptions are made - but you can keep your profile on point as best you can.

    • What do we do? We personalize all our content to make it speak with our voice rather than the voice of a school, tutorial or otherwise. I describe what this means below.

Describe who you want to be even if you are not there yet; don’t cut yourself short!

Your bio description should essentially include the job title you are seeking even if you are not there yet. “Developer”, “Software Developer”, “Software Engineer” are all examples of excellent titles to include in your description. Less is more, honestly.

What are the common issues?

  • No description at all. I talked to a few people who were not aware of the description section of the profile or who were too shy to put anything there. I encouraged them to be bold.

  • Vague or overly personalized description. This is maybe a positive to some but still not what many or arguably most are looking for. Self deprecation also doesn’t work like it is intended to!

    • anything with the word hacking in the bio - Mixed connotations

    • “Creative problem solver with an eye for detail” - Potentially positive, still not ideal

    • “Human with a passion for technology” - Sure, great, I’m looking for a developer to fill a job though!

    These kinds of of bios are all well and good if you are just hacking around or want to describe yourself how you want but it is a missed opportunity if you are job hunting. Whatever it is they are looking for they want to see which is likely just some variation of “Developer” or “Engineer”.

  • Remove references to being Junior (slightly controversial)

    • I think you are better off omitting junior from your descriptions basically everywhere. The Job will decide whether you need to have junior in your title i.e if you apply to a job with the title “junior developer” you are still a developer, software developer… maybe not an engineer… this is a can of worms. Honestly there is no harm in leaving off junior from your description. It doesn’t help and may only harm. I was advised this by one of my first mentors in the industry to avoid paring myself down with the language of junior.

Use a good Image

  • For better or worse, Github includes your profile image with every link to a repository shared on mediums such as Linked or for example in Slack. It is the image that unfurls when a repository is linked somewhere so may as well make your image a good one to make a good impression! If you have a good photo or personalized image like even a bitmoji of you that you that is arguably the best and most likely to build a connection.

what are the common issues?

  • Default gravatar - lacks any personality or identifiability. Missed opportunity.

  • Something other than a professional photo or image - potentially a negative.

Put a lot of stuff on there but don’t spam it

GitHub is a place to document your learning process as well as a place to show the polish you want in a portfolio. You want to present your profile simultaneously for the non technical viewer as well as the curious technical viewer.

  • A less technical viewer like a recruiter might scan your profile and see your repos - details like the quanitity of repos, your pinned repos, your profile image, your description. They may click a few ReadMe’s and look for deployment links and technology keywords before ticking a checkbox to say “interview this candidate” or “pass off to the technical team for a look”. They may not actually read your code at all directly.

  • A technical viewer might see that you put in 120 commits on your first project and took it from nothing to what it is today, and that you used a build process to minimize your code that you deployed. They may even click into the history of the project to see a window into your development process. They want to see you know how to use Git. Branching? Releases? Tags? these can all help you.

You are ideally aiming for quality not sheer quantity of repos and commits but in general more is better! Quality is contextual - make ReadMe’s! A broken or outdated repo or project has value if the ReadMe and surrounding information can put it into context. Suddenly your “broken code” or “incomplete project” becomes a documented piece of progress you made. Don’t let perfect be the enemy of the good.

What are the common issues?

  • Common: barren profiles.

An empty profile wont help if you submit it as part of a job application and maybe it will harm you. I have talked to one hiring manager who particularly claimed frustration with empty GitHub accounts submitted with job apps. Even if you don’t have a lot of original content with a little exploration of forking and starring projects will go a long way.

  • Less common: spammy profile.

Forking everything and starring hundreds or thousands of repos (I don’t know a number but for discussion lets say more than 400+ repos is a sign you should start trimming down, not expanding.). Unless you are really a machine not many will have ReadMes or context to be useful to a prospective employer. It maybe shows you are very active and clicking lots but it doesn’t show care and attention to what you present.

Create a personal profile ReadMe

This is a little chance to show off what you are and what you want to be. To me it shows you someone is engaged with the GitHub platform and I think it demonstrates a perception of being a plugged in developer to some people. Markdown! The language of ReadMe’s! the personal profile ReadMe is a chance to demonstrate your knowledge of Markdown.

What are the common issues?

  • No profile ReadMe… just a small missed opportunity. Not the biggest deal but hey.

Rebrand Schoolwork and tutorials as personalized content

Make your profile speak with your voice. Not the voice of a school or tutorial.

I strongly advise putting in a little effort to tweak and transform some of your school work and tutorials into more personalized content. This is not the same as claiming its all original work or misleading people- it is about rebranding it to present your own narrative on what the work is rather than presenting just another course you plugged through.

What we are trying to avoid is your profile coming across like “just another student” or “just another bootcamp grad”. With just a few small tweaks you can put your mark on potentially every Repo of school work or tutorial work to give off a potentially much more positive impression.

What do you mean?

Remove upfront references to your bootcamp, school or tutorial from your repos and ReadMe’s

  • You can see from my GitHub history that I had originally littered it with references to my bootcamp (Web Development Immersive Cohort 7 in Atlanta) but that I gradually removed almost all of these references. They aren’t really of any particular interest to a prospective hiring manager or developer: they only clutter and potentially give a perception of being inexperienced.

  • Add personal descriptions for your repos showing what they mean to you and what their context is rather than just boilerplate. Consider adding a short description as if you had to “sell” the project to someone.

    • “Flatiron MERN Stack Project #4” becomes “Company Visualization manager built with the MERN Stack; deployed with Firebase”

    • “CompSci200 Arrays and Functions” becomes “Arrays and Function demo, built with Java; build instructions in ReadMe”

Personalization Example:

ReadMe for “CompSci205: Databases Tutorial”.

Course Work for CSCI205. Exercises from chapters 3-5 from Database programming 5th edition;

transformed into…

ReadMe for: “Company database built with MySQL”

Example company database project built with MySQL utilizing foreign key relationships and a variety of data types. Committed over a week long period; plans to expand project in future. References: Chapter 3-5 Database programming 5th edition

It may still just be in fact school work but it is rebranded and gives a different impression: it speaks with a voice from you, not the school or tutorial. It is literally just rewording a few words in your description: I recommend doing this with everything and at least doing it for your 4-6 pinned repos.

Have 4-6 Pinned repositories with full Readmes

Pinned ReadMes are what the viewer will definitely see when they see your profile (the default is to show your most popular repos). If you do not do much more try and pin 4-6 of your best repos and make them have good full ReadMe’s.

Full ReadMe example: project FreeSpot circa 2016/2017

Freespot isn’t perfect but its one of the Github projects that got me my job. Admittedly I haven’t changed the ReadMe much or updated the project much since then. Some of what is in the ReadMe isn’t fully inline with my own advice. Again, your ReadMes don’t have to be perfect!

What makes FreeSpot’s readme a “full readme”?

  1. A link to a deployment at the top of the ReadMe
    • I was told by one software engineer I interviewed with for an internship “If there is a link there, I will click it”
  2. Reasonably clear build instructions near the top (in case they do want to run your project or even if they don’t)
  3. Screenshots of the app or project in action (again, they may not have time to run your project)
  4. A summary or description of the project as it exists (what is the goal of this? it’s more than just to finish a tutorial I hope)
  5. Description of goals or future development (go hog wild! show that you care even if it’s unlikely to progress)
  6. List of any contributors or citations for inspiration/code used
  7. Technical specifications - Drop in names of tech and libraries used here for the viewer’s benefit. Remember the viewer of your GitHub may be less technical! nothing wrong with listing HTML5, CSS3 for example.

Add Topics to your repositories

The benefit of topics i.e similar to tags is that it adds/amplifies keywords that a recruiter or hiring manager is looking for. There is the potential that they will find your repo and then your profile by searching for topics.


Engagement! a little goes a long way. Every time I look at I find a cool Repo that I want to star or fork and I think you might feel the same if you check it out a few times.

This is my pure biased opinion- I really like it when I see someone has starred a bunch of stuff. Not like spammy amounts of stars but has a curation aspect to their GitHub. A lot of what we do as working developers is curate libraries and tools made by others that we we want to use - not as much original work goes on as you might expect. Someone engaging with popular stuff on trending is one gauge of how plugged in they might be with the software world at large.

OSS Contributions: the gold standard

I can’t do this topic justice: it deserves a whole blog to itself. I am also not the best to write about it because I have no particular open source contributions to my name on Github.

Open source contributions are arguably the best currency in your belt on GitHub towards getting a job and worth researching getting involved.

And with all that said…

GitHub is not everything. Still, it may be a ingredient or hurdle to get over to getting your first gig or next gig. It is worth putting some detailed effort into it if that is what you want to get out of it. I hope something from this blog has been useful to you.


Update: This mentee got a job! “They absolutely looked at my github. It was only brought up for a second on my final interview and they liked it a lot. I believe they said something along the lines of how active I was, but they also talked about my projects I have pinned. They didn’t know about my portfolio site, so I’m sure they saw it over github.”

It really was excellent opinionated advice, I would encourage others to reach out especially if you’re like me, and unsure of what to do to break into the field. That 20-30 minutes was quite the confidence booster

Thank you for looking at mine, Morgan. I also encourage folks to chat him up for some advice

Just met with Morgan, who shared many useful insights. I highly recommend it if any other aspiring developers have the opportunity. Thanks, Morgan!

Update: Hey @morganm, I just heard back from a recruiter that she is interested in moving me forward in the interview process only because of my GitHub profile. Just wanted to let you know you’re making a difference and it’s appreciated.

Thank you so much for sharing your insight and advice. It’s awesome that you’re doing this. Every little thing you suggested was incredibly helpful. I’ve started making some improvements and there’s a lot more I still want to do based on your suggestions

Directed guidance and loads of information. Thanks for the mentoring @morganm . Now to get started on that homework! Can’t thank you enough

Just got off of a zoom mentoring session with @morganm. He had a ton of practical, actionable advice which I intend to put into practice asap. I feel super fortunate to have found and Morgan and the rest of the helpful, friendly folks on here. Thanks again, Morgan!

Morgan gave me insightful feedback on my GitHub and taught me ways to highlight specific repos, ways to keep up to late with the latest happenings in tech, and provided helpful suggestions about how to streamline project descriptions to make it easier for potential employers to browse my projects. I even got a few bonus tips about app deployment! Thanks for answering all my questions, Morgan!