What to include on project READMEs as a beginner in tech

When presenting a project on your portfolio there is information you can include alongside it to provide context around it. This can be useful for those who is looking at it to understand it without diving into the code (e.g.: a recruiter).

What I will suggest is targeted at juniors in tech that want to showcase their projects, potentially on GitHub, when looking for jobs and maximize the first impression when your project is looked at.

Here are some sections or paragraphs you can include in your READMEs:

• Purpose and description of the project so that the person reading your portfolio can understand the project in the first seconds of reading the project information.
• Features implemented in the app, what you achieved while coding the project. This is so the person looking at your project can
• User interface examples associated with the project. If the project has a user interface, you can include a GIF or image of the user interface. If it’s an application that runs on the terminal, you can create a GIF that shows how to work with it. This is good to give an idea of how to interact with the app, and what someone would see if they ran the project.
• Tech stack including programming languages, libraries, and framework your project uses (e.g.: python, react, …). If you have a frontend app that uses an external public API, do mention that.
• Instructions on how to set up, run and use the project. This is good, if someone wants to run the project from scratch, they should have everything they need to know on the README of the project, without having to need help from you.
• Future ideas for the project, if you have ideas of how you would extend the project, include them, even if you are not going to complete it. This could be, for example, increasing test coverage, or using a better application architecture, implementing login functionality, etc.
• Technical challenges you’d like to highlight. If you can, try to explain some technical challenges you’ve faced with the project and decisions you’ve taken. This will show you’ve put some thought into what you’ve done.

Now, imagine, what if you have some projects that not necessarily have a user interface? Here are some cases I thought about:

• If you developed a backend REST API as part of your project, you can list the endpoints you created to give an idea of how to use the API separately.
• Once, I got asked what about projects that are CLI programs or scripts (e.g.: SQL queries you created, R projects, Jupyter notebooks). You can have examples of use cases of the project and still showcase why these are useful. For CLI programs, that you run on the command line, you can include GIFs or images of the app running on the terminal.