DEV Community

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

How to create a good README.md file

Julia 👩🏻‍💻 GDE on February 09, 2024

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 wha...
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
 
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
 
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
 
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
 
andylarkin677 profile image
Andy Larkin

everything ingenious is simple!

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
 
martinadamsdev profile image
Martin Adams • Edited

Fantastic guide on crafting an effective README.md file! Your seasoned advice and structure tips showcase your expertise. Gratitude for sharing these invaluable insights.

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
 
sinazinsaz profile image
Sina Zinsaz

Thank you for your good post, it was useful

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!

Collapse
 
steve-lebleu profile image
Steve Lebleu

It depends strongly of the target. As developer, the first expected area will probably be "Install", next "How to" with clear and concise code examples ;-)

Collapse
 
lilxyzz profile image
Travis

Great post, thanks for sharing 🙃

Collapse
 
yuridevat profile image
Julia 👩🏻‍💻 GDE

Thank you, Travis.

Collapse
 
z3phyronsnides profile image
Z3phyron-Snides

Nice!!, thanks for sharing this

Collapse
 
yuridevat profile image
Julia 👩🏻‍💻 GDE

You are welcome, thanks for your comment.

Collapse
 
ricardogesteves profile image
Ricardo Esteves

Nice article @yuridevat , thanks for sharing it! 👌

Collapse
 
yuridevat profile image
Julia 👩🏻‍💻 GDE

Thanks Ricardo.

Collapse
 
alexroor4 profile image
Alex Roor

This article couldn't have come at a better time for me. It addressed exactly what I needed to know, and I'm grateful for your insights.

Collapse
 
yuridevat profile image
Julia 👩🏻‍💻 GDE

Thanks for your comment, Alex. Glad that it helps 😊

Collapse
 
random_ti profile image
Random

Thanks for sharing💖

Collapse
 
yuridevat profile image
Julia 👩🏻‍💻 GDE

You're welcome 😉

Collapse
 
astrodevil profile image
Astrodevil

Nice post, proper structure of README can ease user and builders efforts to understand a project.

Collapse
 
yuridevat profile image
Julia 👩🏻‍💻 GDE

Thanks Astrodevil.

Collapse
 
folt3k profile image
kamil.foltyniak

great!

Collapse
 
ranjancse profile image
Ranjan Dailata

Great blog post.

Suggestion -

Get the hands-on experience with the visual look and feel based mark down editor? use the below options.

Collapse
 
mopano profile image
Mopano

That was amazing 😍