DEV Community

Cover image for How to create a good README.md file

How to create a good README.md file

What is a README file?

The readme file is the first thing a user will see when viewing your repository. It gives the user an idea of what the project is about, what language was used, what the terms and conditions are, what your project can do, shows screenshots of your running application, etc.

Why is it important?

This user could be a recruiter, your future boss or client. Therefore, it is important to note that the README of your project should answer the what, why and how of the project.

Therefore, it is important to include the most important information, give a clear description of the project and the technology stack used, and provide links and further instructions that may not fit into the README file to avoid unnecessary searching through all the other files, which could cause the user to simply lose interest and move on to the next potential employee.

I cannot stress enough how important it is to write good documentation about the project. Not only is the user looking for information about the project itself, but they also see your documentation skills, your attention to detail, which could bring you that much closer to getting a job.

If you've read other articles of mine, you've probably noticed how important it was for my career to have learned other skills besides programming that ultimately helped me get a job. And good documentation was one of them.

What to put into a readme?

Here are some guiding questions that will help you:

  • What is the project about?
  • Why did you develop it, what was your motivation?
  • What problem does it solve?
  • What have you learned?
  • What makes your project stand out?

I will show you how to convert these questions into text.

Possible structure

Description
Purpose and description of the project so that the person reading your portfolio can understand the project in the first few seconds of reading the project information.

Tech stack
Tech stack including the programming languages, libraries and frameworks your project uses (e.g.: Python, React, ...). If you have a front-end application that uses an external public API, please mention this.

Design
Examples of user interfaces associated with the project. If the project has a user interface, you can insert a GIF, video or image of the user interface.

If it is an application that runs on the terminal, you can create a GIF that shows how to work with it. This is good for giving an idea of how to interact with the application and what someone would see when they run the project.

Features
If your project has a lot of features, you should add a Features section and list them here.

How to run the project
Instructions on how to set up, run and use the project. This is good if someone wants to start the project from scratch, they should find everything they need to know in the project's README without needing any help from you.

If it's simple, you can include it in the readme file. You can also refer to another file in your project if the instructions are longer.

You should also host your project e.g. using Netlify, so users can open the deployed app and use it right away to see how it works. (Keep in mind that not every recruiter looking at your GitHub profile has a solid understanding on how to set up a project locally.)

How to style a readme?

The .md extension in README.md stands for Markdown, a lightweight markup language with a simple syntax for text formatting. It is a very simple language for creating beautiful and presentable readme files for GitHub.

Therefore, you can use typical markdown language, like

# Heading 1
## Heading 2
### Heading 3

Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.
1. First ordered list item
2. Another item
β‹…β‹…* Unordered sub-list. 
1. Actual numbers don't matter, just that it's a number
β‹…β‹…1. Ordered sub-list
4. And another item.

[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

![descriptive alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")
Enter fullscreen mode Exit fullscreen mode

and much more. Make sure to get the most out of it.

Here are two examples of my beginner projects I applied for jobs three years ago. I would now make them even more detailed as described above.

GitHub logo YurisCodingClub / sos-animals

This app will help abandoned animals get help from Animal welfare organizations all over the world when people reporting them via this app.

Description

code style: prettier

This app will help abandoned animals get help from Animal welfare organizations all over the world when people reporting them via this app This project was initally created to participate in my first hackathon - Clerk x Hashnode Hackathon July 2021. Check out my article about the project and my experience in the hackathon.

πŸ† This project was one of the Runner Up Winners. πŸ₯³

Blog article: SOS Animals app - a project for the Clerk x Hashnode Hackathon

Thumbnail

The idea is that when reporting an animal, the user will start filling out a form about the animal's situation and location If people want to leave their contact information in the last stage, this should give them the possibility to stay connected with the NGOs and get information about the condition of the animal When submitting the form, the form should be sent to the nearest NGO station.

To…

GitHub logo YuriDevAT / nikki-my-diary

Nikki is an online journal, which helps the user improve their Japanese Skills by writing down their thoughts and feelings. Created with ReactJS, Auth0, and TailwindCSS.

Description

Nikki - My Diary is an online journal where users can pen down their thoughts and feelings to improve their Japanese Skills. Nikki (jap. ζ—₯記 (Kanji)、 にっき (Hiragana) means diary, and it is still common on Japan to use a diary to write down their daily lifes. Besides studying Japanese Grammar or vocabulary with books, it is highly recommended to write a diary in Japanese language to improve their Japanese skills.

Therefore, Nikki - My Diary is being created. It makes it easy for students to write down their feelings from everywhere, setting reminders to keep progress and motivates the user by sending quotes.

Blog article: Nikki - Online Journal App. A project for the Auth0 x Hashnode Hackathon

Thumbnail

Project Setup

The app contains 3 views:

  • Home view - with description about the app and motivation quotes
  • Profile view - where the user can add their diary entries
  • Calendar…

Top comments (51)

Collapse
 
brian_curricular profile image
Brian G.

Great post and a great recommended structure.

There are more potential audiences for a Readme file, not just potential employers.

  • Future You: When you're starting out, you might be tempted to shortcut documentation, because you'll get better at writing code with more experience. But reusing code, even code that requires a fairly significant refactor, can become a superpower. Good documentation is like a gift to your future self.
  • Other Developers / Teammates: To move from personal projects to team projects, you need to get good at writing documentation for other developers to quickly understand your code and get it running on their system. If they have to spend more than a few minutes getting your code running, you'll have to buy them a drink to reward their effort.
  • Open Source Contributors: Similar to above, but a slightly different audience. If you don't write thorough discussions, you'll have a hard time getting users and contributors. Great documentation and usability are the backbone of the most successful OSS.
Collapse
 
yuridevat profile image
Julia πŸ‘©πŸ»β€πŸ’» GDE

Of course, thanks for adding potential audiences, Brian. πŸ™

Since I am mostly focussing on career switchers and CodeNewbies in my blog posts, I didn't think about others than future employers.

Collapse
 
danielrendox profile image
Daniel Rendox

I'm curious why some projects include super-detailed installation instructions and in how much details I should explain mine. Some projects explain how to download git, clone the project, download the IDE, what buttons to click in the IDE, etc.

I think, if a recruiter or a client opens your GitHub project, they won't build it, and instead just follow a link to the running version / download the installation package, will they? On the other hand, if a developer wants to build your project, they already know how to do that. Do I miss something here?

Collapse
 
yuridevat profile image
Julia πŸ‘©πŸ»β€πŸ’» GDE

Thanks for your comment.
Yes, for recruiters a link to the deployed version is indeed the best option, as I mentioned in the article.

I do not agree though for the developer part. A local setup can be soooo different. Some are using docker or kubernetes, some specific npm version, some require local server running or db connection, how to start the app can also differ. As a dev I am not only interested in a project with the language I know best but maybe want to learn something new as well.

Collapse
 
drfcozapata profile image
Francisco Zapata

Thank you Julia for the post... It's great!

I use to add the images with the following syntax:

<img src="./public/screenshot.gif" width="50%" height="auto" alt="Screenshot">

In case anyone can use it. πŸ˜‰

A big hug from Venezuela.

Collapse
 
yuridevat profile image
Julia πŸ‘©πŸ»β€πŸ’» GDE

Thanks for sharing, Francisco!

Collapse
 
roguealien profile image
Rodrigo GarcΓ­a

this is from a perspective that no regular developer will user. I would avoid at all cost images, why? because if you have them from an url they will not remain in that url for much and adding them to the repo is not the greatest of ideas 'cause you'll end up adding unnecessary weight to the repo.

Beyond that I'll add the how to run the repo probably after the description 'cause usually there's not a lot of steps and a couple of terminal commands will be enough. Otherwise I think is a great way to have really useful readme files

Collapse
 
yuridevat profile image
Julia πŸ‘©πŸ»β€πŸ’» GDE

Thanks for sharing your insights, Rodrigo.

Collapse
 
ther4v3n profile image
R4V3N

Graet and usefull post. It let me think if my Readme is any good. Maybe you could let me know.
github.com/The-R4V3N/Team_project_...

Collapse
 
yuridevat profile image
Julia πŸ‘©πŸ»β€πŸ’» GDE

I think it is, @ther4v3n . I would remove the personal part inside the project's readme, this is something which should be added to the readme of your GitHub profile (which I saw you already have) :)

Collapse
 
ther4v3n profile image
R4V3N

Thank you!

Collapse
 
highcenburg profile image
Vicente G. Reyes

Thank you for this article. Now I have a guide on when I need to create a readme

Collapse
 
yuridevat profile image
Julia πŸ‘©πŸ»β€πŸ’» GDE

Glad it helped, Vicente.

Collapse
 
andylarkin677 profile image
Andy Larkin

everything ingenious is simple!

Collapse
 
lilxyzz profile image
Travis

Great post, thanks for sharing πŸ™ƒ

Collapse
 
yuridevat profile image
Julia πŸ‘©πŸ»β€πŸ’» GDE

Thank you, Travis.

Collapse
 
mikiqex profile image
Michal NovΓ‘k

If the target media isn't paper, I'd advocate against underscored text for emphasis, because it's widely understood as links and therefore could be misleading.

Collapse
 
yogini16 profile image
yogini16

This is awesome.
Thank you for sharing !!

Collapse
 
get_pieces profile image
Pieces 🌟

Amazing read! This is so useful. πŸ‘

Collapse
 
felipekiko profile image
Felipe KiKo

Great post! Creating a default structure is good for keeping consistency across all projects! Thanks!!

Collapse
 
robinbastiaan profile image
Robin Bastiaan

When posting on GitHub, do not forget you can also fill in the about section of your project on the right side. Here you can give a brief summary of your project and can complement the readme a bit.

Collapse
 
alyssawink profile image
Alyssa Hanewinkel

I’m a newbie coder and am currently learning how to make a README file, so this was awesome to see when I first opened the app!

Collapse
 
yuridevat profile image
Julia πŸ‘©πŸ»β€πŸ’» GDE

Glad it helps, @alyssawink And a warm welcome to the tech community :)

Collapse
 
alyssawink profile image
Alyssa Hanewinkel

Thank you! I’m excited to start!

Collapse
 
gadrawingz profile image
Gad Iradufasha

If you fully understand Markdown and related stuffs you cannot be stuck while using writing a good README.md file!

Happy Coding!

Some comments may only be visible to logged-in visitors. Sign in to view all comments.