Developer portfolio do's & don'ts


11 min read

Developer portfolio do's & don'ts

So you've now built some projects and you're ready to tackle your developer portfolio, great! Whether you'll need one will depend on your situation but if you're coming from a self-taught background as I was, it's a useful thing to have in your back pocket.

You will also probably need a portfolio if you're looking to start freelancing so that you can show potential clients that you're up to the task. This article won't be focusing on a freelancer's portfolio because it's not my area of knowledge but there is plenty of overlap of useful tips so please keep reading ๐Ÿ˜„.

Building your own portfolio is not an easy task. There is a lot of different ways you can go about the task and I thought it would be useful to write an article that answers some of the questions I had when I was building mine.

Here are my portfolio do's & don'ts ๐Ÿ‘


  1. ๐Ÿ“ž Contact Details
    • Do - Make your contact details obvious
    • Don't - Add social links to accounts that you don't actually use
  2. ๐Ÿ–ฅ Projects
    • Do - Consider adding project case studies
    • Do - Make it easy to jump to the projects
    • Don't - Include the portfolio itself as a project if you have enough other projects to show
    • Do - If you're going to include tutorial projects, customize them in some way
  3. ๐Ÿ˜ƒ About Me
    • Don't - Include your life story
    • Don't - Include skill bars
  4. โœ… Tech stack doesn't matter, performance & accessibility does
    • Do - Ensure the site is performant
    • Do - Ensure your site is accessible
  5. Summary

๐Ÿ“ž 1. Contact Details

Do - Make your contact details obvious

Not making your contact details obvious to the hiring employee/potential client is probably the worst thing you can do. Why go to all the trouble of showing off what you can if you don't make it easy for them to contact you afterward?

Consider adding multiple communication options on your site. This could be through email, Twitter, Linkedin, Github, and anything else you actually use and have a presence on. When your site loads, the user should be able to click one button and be taken to a contact option.

You could do this using a call-to-action on your hero that says something like 'contact me' taking the user to a contact form on your page. Maybe you could add links to your accounts using icons and add them to the hero so the when the page loads they're right there on the screen.

Whatever it is, make sure it's obvious and simple for the person to find and contact you. You don't want to miss out on an opportunity because you made it difficult for them to reach out. Employers are not going to spend very long on your page and they will just move on if they find it difficult.

I remember when I was building my portfolio for the first time. I searched for what contact links are common for someone to add to a portfolio. Common options include:

  • Email
  • Github
  • Twitter
  • Linkedin
  • Youtube
  • Blogging profiles

As a developer you should already have a Github profile which can be added along with your email but the rest are usually optional.

When I was making my portfolio I had a bare Twitter account which I had created a few months prior and an almost empty Linkedin profile. If these are not sites you actually intend on using, don't bother including them in your portfolio. What's the use of showing an employer your Twitter account when you don't post there or contribute anything related to web development and the jobs you may be applying for.

My suggestion would be to start using some of them and begin branching out. The word 'networking' made me nervous when I started but it's really not that difficult to start making connections with like-minded people. Then you can add these profiles to your portfolio and start building a more well-rounded portfolio.

๐Ÿ–ฅ 2. Projects

Do - Consider adding project case studies

There are plenty of great portfolios that don't include case studies of their projects but I think it can help you stand out. You don't need to write thousands of words for each study but adding a little more background to each project can be very insightful.

Tailor each case study to the real world and how your potential employer would look at a project. Consider adding the following elements to the study ๐Ÿ‘‡

  • Project objectives
  • Why the stack choice was optimal for achieving the objective
  • Some of the problems you faced and how you overcame them
  • What you might do differently next time

Showing potential employers that you considered the trade-offs between alternative solutions and tech, based on the needs of the client (or you for a personal project) will go a long way.

Instead of saying

The front-end of this project was built with the JavaScript library React.

Expand on it by saying why this decision was taken with something like this ๐Ÿ‘‡

I decided to go with React for this project because there is a lot of state management required which would be much more difficult to maintain without the JavaScript library. By choosing React I could get the live site up and running faster meaning the client could start trading as early as possible. It would also provide a more maintainable codebase for the future...

Do - Make it easy to jump to the projects

Your portfolio is essentially a house to show off your projects right. Almost like when you want to buy a car. You go to the showroom or garage and the employee walks you around to see some of the cars on show. You're not really interested in anything else but cars. If you like what you see you input your contact details and make a purchase.

The same goes for the portfolio. Make it easy for the user to find the projects so they can see what you can do and then contact you if applicable. How you do this is up to you and there is no obvious best approach.

My approach was first to avoid adding a hamburger toggle to my site and instead just include the link names. I only have three links so there is really no reason to make the user click an extra button to find what they're looking for. On the home page, I also kept the introduction section relatively small with limited text before introducing my projects. After the projects I include a little 'about me' section with a little more info about me which really didn't need to come before the projects.

Try not to leave the user with a mountain of introductory/personal content to scroll through before getting to the projects.

Don't - Include the portfolio itself as a project if you have enough other projects to show

This is something I deliberated at first and so I asked my friends over on Twitter what they thought about it. The general consensus was to avoid including the portfolio itself as one of the projects. This is especially true if you have plenty of other projects to highlight. Instead consider just adding a link to the Github repo somewhere. I like the idea of including it in the footer but it's up to you.

Do - If you're going to include tutorial projects, customize them in some way

It's fairly common to see projects on someone's portfolio that clearly came from a tutorial. We have all taken tutorials at some point and these projects can be a very useful learning curve. But if you want to add it to the portfolio, then customize it in some way that will make it a more personalized project.

For tutorial projects I would recommend not adding to the portfolio and instead just link your Github repo where the code lives. However if you're at the stage where you don't have many projects, it can be a temporary solution. Try changing the design of the tutorial project and some of your own features to it as well.

Personalize your projects to help you stand out!

๐Ÿ˜ƒ 3. About Me

Don't - Include your life story

I have seen plenty of portfolios that include a massive life story of the creator. It takes endless scrolling to get through before seeing the projects. I'm not saying you shouldn't include it, but I am saying you can probably reduce the size of it. Nobody needs to know what we had for breakfast or where we went to school ๐Ÿ˜„.

Give a few highlights instead that will quickly give a better picture of you as a person. Keep it short and concise or move it after the projects on the home page. You could also have a dedicated 'About me' page with more information there and have a quick snapshot of it on the homepage.

As long as you don't have a massive personal section ahead of your projects that require scrolling to get through it, you should be good!

Don't - Include skill bars

This is a personal preference of mine that you may disagree with. You have probably seen those skill bars where the developer gives themselves a 9/10 for JavaScript as an example. In my opinion, this is not very useful information to be giving a potential employer. The employer will find out exactly how good you are when it comes to your interviews.

You could be overestimating your skills giving the employer the opportunity to question you on it which may trip you up. Or perhaps you're underestimating your skills and they deem you not to be worthy of the interview in the first place.

I just think that they don't provide any actual value to your portfolio. You can include the tech you are comfortable with but I wouldn't add a rating for what you think your skill level is. Use your projects to highlight your skills and what you could do better instead.

โœ… 4. Tech Stack doesn't matter, performance & accessibility does

Do - Ensure the site is performant

The content and design are often the main focus for new developers when it comes to building the first portfolio. But good performance and accessible content are two incredibly important factors of any website that you need to get right. You could have all of the best projects in the world on your portfolio, but if it takes 5 seconds for the page to paint and render then what's the point?

No potential employer is going to consider you if they visit your site and it takes forever for it to load. They will think that you don't know how to optimize a site which will set off some red flags. At the end of the day, the stack you use to build the site is irrelevant. But it should always be performant and accessible. General tips for making it performant are as follows ๐Ÿ‘‡

  • Load the content you need for the visible screen and defer the rest when possible
  • Optimize any images you may have
    • Use modern formats like WebP with a fallback option
    • Use a compressor tool like
    • Use the correct image size for the device size
    • Lazy load images
  • Bundle and minimize your files

Use a tool like Lighthouse to audit your site and give you potential improvements to make for performance as well as accessibility.

Do - Ensure your site is accessible

Make sure you use colors that contrast with each other so that users with deficiencies in viewing colors are catered for. You can use a tool like WebAIM: Contrast Checker to help you with this.

Make sure you always add alternative text to all of your images so that users using assistive technology can still understand your images. Also, try tabbing through your site as an impaired user may do. Ask yourself this ๐Ÿ‘‡

Is the tabbing order logical?


Can I still operate the site as any other user would?

If the answer to these questions is no, you definitely want to correct this. Firefox has some great features in its developer tools for helping you view this information.

Navigate to the Accessibility tab in its developer tools and click the button 'Show Tabbing Order' to highlight all of the tabbable elements on the page. There is also a lot more information related to accessibility here like element roles so have a look around and see what improvements you can make.


Let's quickly summarize the main points. Make your projects stand out as the highlight of the portfolio and ensure your contact information is easy to access. You can include information about yourself but don't make it detract from your projects. Finally, ensure the site is fast and accessible.

If you can manage all of this with some good projects on there as well, you're on the way to becoming a software developer. This is not to say that will be guaranteed to find a job. But it will help you get your foot in the door and perhaps receive more interview opportunities. It's then up to you to back up the stuff you claim to know from your portfolio.

I hoped this will help you in some way because making a portfolio can be a difficult thing to get right. Looking back at mine now, there are many things I would change and I'm sure I will be building a much-improved version sometime in the future for a bit of fun. But everything I have mentioned in the article stands true for me at least.

Reach out to me @Kieran6dev for any questions or concerns.

Until next time ๐Ÿ‘‹

Did you find this article valuable?

Support Kieran Roberts by becoming a sponsor. Any amount is appreciated!