The README file: How to Help Others Understand Your Project

Are you sharing your projects on GitHub but still think you are missing something? Would you like to make your projects look more professional? Then you should definitely include a README file!

A README file is like your project’s cover letter, and it’s also very good practice with documentation and writing. At the end of the day, you don't only want to build something new and just add it on GitHub but also share why you did it, summarize your learnings and, finally, why not? Why not make your projects more attractive and stand out from the countless projects out there?

What should a README file contain?

I write to discover what I know – Flannery O'Connor

First of all, think of a README file as your rubber duck. It will help you focus on explaining what your project’s main goal is and how you want to achieve it. The whole documentation doesn't need to be extra long, but it should explain the project well. It is not about quantity (amount of words), but quality (other developers should understand your project). Therefore, I would suggest you focus on answering these 3 key points: what, why, and how?

Below you can find a possible README file structure:

• Title
• Overview
• Description
• Final project link
• Technologies used
• Learnings
• Author/contributors

Title

Start with a simple title that describes your project clearly (e.g.: React weather app).

Overview

Display an overview of your final project. It could be a static image or a gif. For example:

Description

Describe your project in a couple of sentences. Explain what you built, which features you implemented, and why you built it: what was your goal or motivation? Was it your own idea, a team’s idea, or did you find inspiration somewhere else? If you created a project following some tutorial, make sure to link it. Doing so will help other learners find the same resource you use, and it will show potential recruiters all the resources you are following. Moreover, linking the original source is the right thing to do.

Link to the project

Link your deployed final version so that anyone can see it and test its functionality. This will make your project way easier to understand to anybody who visits your page. And it’s a chance to demonstrate that you know how to deliver an application to a server.

Technologies

List all technologies involved (programming languages, frameworks, libraries, APIs, etc.)

Learnings

Mention your learnings: go deeper in this section. You can share what your initial ideas were, what mistakes you made, how you solved them, which technologies were super useful or you learned about, etc. If you have a blog and feel like creating a tutorial about the project or any specific technology involved in the project, you could link it here. I am sure it will help your project stand out, and many developers or newbies will appreciate your effort.

Author/contributors

Link your portfolio and/or any other contact points (like Twitter or Linkedin). If you built it within a team, then mention the contributors.

Exercise!

Enough reading—now it’s time for some writing! Grab some of your study projects, and add a README following the suggestions from this article. When you are ready, please share a link in the comments! We all would like to see your project.

And that's it!

Are you ready to start spreading the word about how awesome your projects are?

This post was a collaboration with Christina Padilla: an online marketing specialist and a self-taught frontend developer based in Berlin with a passion for technology, learning, and solving real-world problems through code.