Phil Choi argues that a strong README separates good programmers from great ones. It should document your project's dependencies, install steps, file structure, scripts, and troubleshooting. A clear README shows you understand your code and can work with a team.
Chapters
I recently had a discussion in my discord and a question came up. What will get you the opportunities that you want as a programmer? To paraphrase this question, how can we become the developers that are wanted in these companies? The answer is a good readme, one of the most important files in the project. If you can write a good readme, it will separate you from the pack as a developer. It will get you those opportunities you want because you will be seen as a team player. It will also help you understand your own code and allow you to explain it in a structured way. In this video we will take a look at how to write a good readme by showing you how I've written my readmes in the past and hopefully it will help you ascend you in your long career as developer. So my name is Phil. I became a senior developer at the age of 30. If this video becomes a value to you, please like and comment on a useful tip that can really help us developers become more valuable in the company. I read all my comments and would love to give my input on these as well. I have written like a bunch of readmes. That's how I start all my projects. Anyways, when I write a readme I tried to kind of. You could either do it in notion, but I like to do it on readme because it's like project based. So like this is one of my projects, it was like a coffee app. So like I write a little description about like what kind of project it is and then I like to put like the node version because nowhere in the project it'll tell you like what node version it is. And that's pretty important because sometimes it won't say it and then like someone can't run the project because their node version isn't correct or something. And same with like whatever version you're using, whatever styling you're using, entry point to the app, how the files are structured and then like how you're linting your code. Or like what if you're using Husky or you're using like any kind of formatter and then what what you're installing. Because like yes you can use pnpm, NPM or yarn, but it's good to kind of just use one because you'll have like a yarn.lock file or like a dash lock JSON file. So things that you have to outline in your product is like how to run your project right? You should, you have to, you should install the dependencies and how to deploy. These are like my scripts. So I'm just pointing those here. And I have like these scripts here like running iOS project or running an Android project. And then I have maybe like my Deploy iOS script here which I was using fastlaner Deploy Android Fast Lane and then I have them in deploy script and had a deploy script which was like a bash script pointed at a bash script. Let me show you that one deploy sh. So it was just running those commands that were inside of the package JSON. So I also like to need like how to run an upgrade in a project. What kind of like eslint prettier and husky strategy to have and how to set it up and then what steps everyone needs to take. Like everyone needs to install like husky and then add the pre commit. So the husky works like and then people might be wondering oh, like why do you have this squiggly line for like your SRC folder like the path? And then you're like okay, if you just read the readme I have Babel plugin module resolver and it's all, it's all pointing the square squiggly line or the tilde to the SRC folder which I'll show you guys. Babel config. So I alias this squiggly tilde to the src and I think I have another place somewhere like the tsconfig or something. So it doesn't like cause any issues or something like that. Like the readme will kind of have explanations for like the code. And like if someone asks you like, like I don't know, a weird question or something, you can just point them to the readme or like you know that they didn't read the readme. If they ask you a question that's obviously there. You know, it's like someone asking you a question like before they've googled and you're kind of like, oh yeah, it's cool like for the first like five times or something. But after like on that sixth time maybe you're like have you tried googling before asking me? But anyways, like same with the readme it's like it's the own little mini. Like Google I guess, but like curated. So like also like I like to put like insult steps like in case like my project kind of like breaks or something. Like what kind of things I like to how you would rename the project or how to reinstall some packages because it's my place to kind of like if something happened and it all broke but I was just left with this readme file, I would like to know how to rebuild the project to where it was and kind of just stuff like that you should put in the readme to kind of like help you and share with whoever's going to work on the project. So that's like what I think makes a good readme. Like things to outline, like a description of like the project that you're working on, version of what you're using and the tools you're using. Also like what dependencies and how to install them and like how to like run the project is very important. How to deploy the project, if you have any file pathing, like that's like special to the project, how you do that, why it does that. And then like linting and prettier strategies are always very important. You know, like merge conflicts because of spaces or something is like wasted time to be honest. So that's honestly what I wanted to say. So that's about it. But I mean, yeah, there's so many dead dependencies. Especially like on a react native mobile you have a lot of dev dependencies. So I like to kind of put notes on like especially like not the JavaScript stuff, but like the iOS and the Android folders. I like to like, because you have to make certain like changes in the settings. So like in my projects I like to put like the date and like my initials of when I changed it in there and also in the readme how to change it, kind of get it to that setting that I put it at. So like, I just like to put like what the steps I need to do, like what package I'm using and you know, a readme basically outlines the whole project. It's really good to kind of put a clear understanding of like how to set up the product project, how to deploy the project, how to run the project, what the project's using and you know, let people know that, hey, we're using this stuff. If you want to learn more about that stuff, please look into it. Readmes will kind of help the whole team. Not only help the whole team, but help you as well. So if I can do it, you can do it too. Coding saves lives.
