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.
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?
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.
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
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) :)
Full-stack dev shipping Django/React SaaS and Shopify stores since 2018. 37 client projects, 11 live Shopify builds. I write production war stories so you don’t repeat my outages.
There is some genuinely good advice here, but I'm not sure if "recruiter, future boss or client" are the right target audience to consider when you're writing a readme? I think it should be addressed to a person the app/ library/ tool is intended for. Writing it for a recruiter seems a bit short-sighted.
Edit: I think Brian G below made some good points about this.
You are indeed right, that other developers/users are the main target especially when it comes to open source and contribution. This post was written a long time ago, where the main focus of my articles lied on finding a job with your GitHub profile. And all these points focus on clear structure, good documentation and such for recruiters to get to know your working style!
Name is Gad Iradufasha,
Web developer and System Analyst/Designer
Skills In web development are:
SEO ( Search Engine Optimization),
Building Websites & Web apps.
Visual artist.
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 ;-)
Fantastic guide on crafting an effective README.md file! Your seasoned advice and structure tips showcase your expertise. Gratitude for sharing these invaluable insights.
Dev since 1996. Learning timeline: BASIC > Pascal > C++ > PHP+SQL+JS > Delphi > ASP > C# > SmallTalk > Java > PL/SQL > Objective C > Swift > TypeScript > Kotlin > ST
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.
I am an enthusiastic professional, having rich experience in Product Development with Microsoft technologies.Skilled in C#, .Net core, Web Api, microservices, Azure and AWS to build distributed system
Bringing AI & machine learning right to where you are in your workflow. Supercharging tools like GitHub, VS Code, JetBrains, Browsers, and more! Try Pieces for Developers Suite for free today!
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.
👋 I'm a Frontend enthusiast & full-stack aficionado | Crafting captivating user experiences | Based in Lisbon, Portugal 🇵🇹 | Dedicated to innovation and staying ahead with the latest in tech!
A Professional based out of India specialized in handling AI-powered automations. Contact me at ranjancse@gmail.com, LinkedIn - https://www.linkedin.com/in/ranjan-dailata/
Great post and a great recommended structure.
There are more potential audiences for a Readme file, not just potential employers.
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.
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?
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.
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.
Thanks for sharing, Francisco!
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
Thanks for sharing your insights, Rodrigo.
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_...
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) :)
Thank you!
Thank you for this article. Now I have a guide on when I need to create a readme
Glad it helped, Vicente.
There is some genuinely good advice here, but I'm not sure if "recruiter, future boss or client" are the right target audience to consider when you're writing a readme? I think it should be addressed to a person the app/ library/ tool is intended for. Writing it for a recruiter seems a bit short-sighted.
Edit: I think Brian G below made some good points about this.
Thanks @frogdoestech for your comment.
You are indeed right, that other developers/users are the main target especially when it comes to open source and contribution. This post was written a long time ago, where the main focus of my articles lied on finding a job with your GitHub profile. And all these points focus on clear structure, good documentation and such for recruiters to get to know your working style!
Nice post, proper structure of README can ease user and builders efforts to understand a project.
Thanks Astrodevil.
If you fully understand Markdown and related stuffs you cannot be stuck while using writing a good README.md file!
Happy Coding!
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 ;-)
Thank you for your good post, it was useful
Thanks for sharing💖
You're welcome 😉
That was amazing 😍
Fantastic guide on crafting an effective README.md file! Your seasoned advice and structure tips showcase your expertise. Gratitude for sharing these invaluable insights.
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.
everything ingenious is simple!
This is awesome.
Thank you for sharing !!
Amazing read! This is so useful. 👏
Glad it helps, @alyssawink And a warm welcome to the tech community :)
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.
Great post! Creating a default structure is good for keeping consistency across all projects! Thanks!!
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.
Thanks for your comment, Alex. Glad that it helps 😊
Nice article @yuridevat , thanks for sharing it! 👌
Thanks Ricardo.
Nice!!, thanks for sharing this
You are welcome, thanks for your comment.
Great post, thanks for sharing 🙃
Thank you, Travis.
great!
Great blog post.
Suggestion -
Get the hands-on experience with the visual look and feel based mark down editor? use the below options.