Thread by @oliverjumpertz

Especially when you have no prior experience as a software developer when applying to jobs, you need something to stand out.

One way to show what you are capable of is to build a portfolio, and here is how that should look.

A thread. ↓

1. Why a portfolio?

When you have little to no experience, it isn't easy to show a potential future employer that you can do the job.

Even a college degree doesn't guarantee that you can work in the industry.

Education actually differs a lot from reality.

Education teaches you how things work.

This holds true for:

- College courses
- Tutorials
- Books
- Online courses
- etc.

You often even learn HOW to do things.

But this doesn't ensure that you know how to apply this knowledge.

When a company hires new staff, they look for people who can get the job done.

They need workers able to apply their knowledge.

In the case of software developers, this means turning ideas and requirements into working software.

Prior work experience on your CV shows that you somehow managed to stay employed for a certain amount of time.

It gives some security to potential future employers that you were already able to do the job.

But if you miss this, it becomes difficult to assess you.

A portfolio of projects can give some security to interviewers that you know how to create software.

You probably developed this software on your own, but you can use many of the best practices that teams in the industry use every day.

A few personal projects, done right, can give you enough credibility that interviewers really consider you for a position and don't only throw away your CV because they look for someone with more experience.

And even if you have experience, having something to show could give you an edge over another candidate.

Most of the work we, as software developers, do, is proprietary and closed source.

Having open projects lets you showcase your skills even better.

2. What your portfolio should contain

You should aim for at least two projects in your portfolio. Three if you can find the time.

Those projects should be closely related to your position or the position you want to fill in the future.

As a backend developer, you could create two to three different micro-services with APIs and such.

As a frontend developer, a website, a SPA, or something like this can showcase your capabilities best.

Your portfolio projects should:

- Have publicly available source code
- Be running and working as intended
- Be covered with tests
- Have a demo deployed somewhere
- Have rudimentary CI/CD
- Be documented (At least a README)
- Be unique among them

You don't need to come up with a unique idea that no one has ever done before.

You don't apply for a product designer position. You apply for a job that requires you to turn the ideas of others into code.

Copy an existing product, and perhaps give it your own touch.

Even a ToDo-App, if executed correctly, can be a great portfolio project, especially when you don't want to spend weeks or months on your portfolio.

Just make sure it's at least large enough to really show what you are capable of, and don't build the same app twice.

3. Building your projects

Spend some time on your projects.

You don't do yourself a favor when you simply throw some unreadable code on GitHub, lacking documentation and having no tests.

All this does is giving a bad impression of you.

Your goal is to create a professional and small software project with best practices from the industry.

You should follow a few basic rules that we are going to cover next.

-> Keep your code simple

Don't try to impress interviewers with "ultra clever" code.

Clever code smells. Better keep it simple.

Readability is one of the most important things in the industry.

It makes the difference between delivering a project on time or far too late.

-> Organize your code

Don't throw around code mindlessly. Organize your code into folders and modules.

For example, components into a components/ folder, utility logic into utils/, business logic into services/, and so on.

Import and export logic where necessary.

-> Add comments where applicable

If there are places in your code that you can't make more readable, add comments.

Yea, it's considered bad to explain a what, but especially as a junior, better be honest and help viewers understand what happens.

-> Document your project

There are different views on code documentation, but I usually view it this way:

Everything that is somehow publicly available within your own project or to someone else pulling your project in as a dependency should be documented.

This means either:

- Docstrings
- JavaDoc
- JSDoc
- or whatever your language of choice offers

Follow the conventions of your language to create good code documentation.

Additionally, add a readme to your project.

It should contain:

- A description of the project
- An introduction to how to work with the source
- A guide on how to run your project locally
- A guide on how to deploy your software
- A list of runtime dependencies like a DB

- A link to a running demo version
- How to use your project

Someone completely foreign to your project should be able to understand what they look at and what the repository contains.

They should also be told how they could contribute to your project if they wanted to.

This includes how to clone the source, which tools are needed, and what commands to fire to build, test, etc., your project.

Next, your readme should state how anyone can start your project locally, so they can quickly take a look at a running version.

After this, it should state how your project can actually be deployed to a "production" environment. Be it Heroku, AWS, Vercel, Netlify, etc.

If your project has dependencies like a database, an API that requires an API key, or an account, it should also be listed.

A link to a running demo of your project makes the readme nearly complete.

A guide on how to use your project finally finishes the readme.

State how the APIs of your service can be used or how your app is to be used.

This is enough information for anyone to get along.

If a hiring manager or someone at a company you apply to decides to spend a look at your projects, they will have a far easier time getting around and evaluate what you built.

-> Test your software

This is a mistake even many senior developers still make when doing take-home tests or building a portfolio.

Tests are not optional.

Yes, there are companies where tests fall short because of "reasons," but this is not the norm.

Being able to write unit tests is usually expected from any software developer nowadays.

Not paying attention to quality assurance thus leads to some negative points because you make the impression that you either don't know how to or don't care.

-> Deploy a live version of your software

Publicly available source code is great, but not all hiring managers or engineers have the time to go through it.

If you have a running version, you give people the chance to see at least the final result of your project.

This gives hiring managers a chance to see what you actually built and perhaps prepare a few questions about your projects for you.

You can then probably go through the source code together later.

And even if not, you will be able to talk about your creation process.

-> Spend some time on CI/CD

Of course, DevOps engineers and SREs in the industry take care of larger deployments, but some basic CI/CD ensures you can show that you know about the full software lifecycle.

It's not about advanced pipelines. It's only about the basics.

Make sure:

- Your project is built and tested on each commit
- Can be deployed to your production environment
- Optionally does merge checks

That's something that takes you only a few minutes to configure with GitHub Actions, for example.

4. How much time you should spend

You are probably already busy enough with your life, family, friends, and hobbies, and that's fine.

Putting in all this additional work takes a lot of time, only to get a job.

You can optimize the time you spend on your portfolio projects by limiting their scope already at the beginning.

You don't need to add all features that seem interesting or could be useful.

If your app misses an admin UI, then be it. Prefill the DB with a script.

The only thing you should aim at is to deliver something that "feels complete."

A user should not get the feeling that your project is unfinished. But you should usually get a feeling for yourself for that when you try your own project out.

As a good rule of thumb, but largely depending on your experience, you should only build something that roughly takes you ten to fifteen hours.

You can still extend your projects later, but if you don't have much time, it's a good time frame to begin with.

5. Thread end

That's it for this thread. I hope you found something useful in it for you.

If you enjoyed reading this thread, consider dropping a like, retweet the first tweet, or follow me (@oliverjumpertz) for more content like this.

6. Attribution

Thank you very much, @thinkLikeADev, for the original idea to write about what a good readme should contain! 😊