As nowadays, Software is really shaping the whole world. There are so many companies and products built by technology that help the human race in their activity. Let’s say, when I want to discuss with someone, I just open WhatsApp or Telegram, and I can ask all of my friends there.
When I want to book a hotel or just a small room, there’s already AirBnB. Flight ticket? There are Traveloka or Tiket, etc. For Transportations? We can use Gojek or Grab. Hungry? Go-Food or Grab-Food. (I’m talking about tech-product in SEA especially in Indonesia).
All of those products were created by the technology itself. And no wonder, Software Engineer becomes the hottest job nowadays. To make a great product, it needs great software. And to make the great software, need the great engineers behind them too.
Not only commercial products but open-source products also become going popular now. Let’s say like Kubernetes, Docker, Golang, NodeJS, etc.
Not only the big open-source project. There are a lot of small open-source projects too, like a library for specific functions. And it can be written in Golang, NodeJS, Java, etc.
But, the problem is, there’s a lot of projects that might be useful to society but it’s doesn’t have a good or descriptive README. And it will make the library or open-source project become useless or my uncle said: “not classy”.
If this happens for the library (doesn’t have the README), then we can just switch to another library that has a similar function and has a better README, to explain how to use it, how to run and install any dependencies.
But what happens if this happens to internal projects? For the internal company's project? Can we switch to another service that has a similar function? LOL! 🔥
What is README?
Anyway, before moving further, let’s find what’s the meaning of README? Why is it important? How to create it?
So, if we look from Wikipedia,
A README file contains information about other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called READ.ME, README.TXT,[1] README.md (for a text file using markdown markup), README.1ST — or simply README ~ https://en.wikipedia.org/wiki/README
In general, README is just a simple general information of software/project that exists in the same directory/repository of the project. README is used to explain the details project in a short way. Like, what is the project used for? What are the dependencies, how to install it, how to compile it, or how to run it in local? Where to go when there’s an issue. What is the current status of the project, is it experimental, production, or just still on development.
We put all of that information in the README. So when another engineer reads that project, they can understand the project just in 5 minutes without having to look to the source code, what is the project used for, like the function or the endpoint (if REST API projects), etc.
Why is it important?
Yeah, why this is so important?
Before saying this is important, I want to clarify first, all content I write here is purely in my opinion. You can be agreed or not, but I’m saying what is the right thing based on my experience. If you do not agree, let’s discuss in the comments. Maybe I’m wrong, maybe I've experienced the wrong practice because I also want to learn what’s the right one.
So why this is important?
First, let me ask a question, what is a good software? How do we define that a software is good enough?
In my opinion, one of the parameters to say software is “Good” is when that software is useful to others. Meaning that it’s used by others not only us who developed it but other people too. It can be engineers, it can be users, it can be a system, it can anything that used that software.
And building software is really cost us much time, and maybe money so it can be used by others. Also, when building that software, we maybe working on the team. Writing the same product to make useful software.
And that’s when we have to think about README projects. I have a few reasons why we need README in our projects. Such as:
- Engineer Movement
- Visibility and Development Pace
- We’re not the only one!
Engineers Movement
When working in a company, it’s true that we won’t work on the same project in our lifetime. There will be a new interesting project or maybe we will move to another team. Or maybe we will be promoted to a higher level, so we won’t be doing coding again.
If this happens, the new engineer that will responsible for our sh*t will be having a hard time for the transitions. It’s okay if it’s only one repository. But what happens if we leave many repositories that we maintained. The new engineer that replacing our positions will be having a hard time and stress.
Or maybe, we worked on a team. And all of our team members already understand very clear the whole projects including other project repositories. And even without the README, every team member already understands all of the repositories used for. And then we started to think, README is not really important. Because everyone already understands all of the repositories that our team maintained.
But, the things is, if our company grows and scaled, so eventually, our team will be growing too, we will hire a new engineer to help our team to manage the services. Unless the team is super-engineers or we call 10X engineers, that can maintain everything only by just a few engineers without hiring new engineers, if that’s the case, my apologies to underestimate the team’s skill. 🙇♂️
So, no matter how boring is writing the README, please keep in mind, we’re not the only one who will be working on the project. We also need to think about the future hired engineer that will handle all of these projects.
Let me tell you a dark story, I’ve experience working on a project that doesn’t have a README. It takes 3 weeks for me only to make it run in my local. There’s no guidance. I need to look to source code, what are the configurations, such as database URI, PubSub env variable, etc. And it’s really frustrating!
Visibility and Development Pace
Only by seeing the README, we can understand what is the repository used for, without spending times to look on the source code.
Let me give you a comparison. I have 2 repositories here:
In 5 seconds, can you understand how to use both of them in your project? Both of that repositories are a library for math operations for multiplication. Which one is more understandable?
So that’s one of the reasons why we need to put README in our projects. It doesn’t have to fancy, has color and everything. At least, we can use it without asking the person who built it. We can import it to our projects (if it’s a library). Or we can run it locally if it a service or REST API project.
And the faster engineers to understand about the repositories, the faster they will work. And the development pace will still the same from the start to the end.
We’re not the only one!
Then there’s a question, “what if I built software for myself? It’s useful for me, but maybe not useful to others”. Well, if it just for personal consumption. It’s up to you to create the README or not. But, when you solve a problem for yourself, it can be people’s problem too. So, putting a good readme maybe help others to use it.
Let me tell another story that happened a few months ago, it’s when I’m developing a feature in my side projects. I found a blog post of an engineer that says he creates a library as his side project just for fun. But I think, what he worked on is amazing. He creates an Angular plugin for the text editor, which has the same function as Medium has.
But when I’m looking to the repository in Github. (I don’t want to post it here, because I don’t want to make it look bad since he built it for fun). I read the README, and it is not updated. I can’t use the library. WTF. So then I just passed it and looking for other libraries that have similar functions that have better README and guidance on how to use one.
So, what I’m saying is even it’s just for a fun project. Not used in production or in our company. Putting an updated and descriptive README will help millions of people out there. We don’t know that what we worked for side projects will useful to others on another side of the earth.
Takeaways
So takeaways from this story are we have to create the README in every project we worked on.
Even I still learning and enforce myself to create README in all of my projects. I remember in my previous company, sometimes I also too lazy to put the README. But at the time I don’t think about how if the team is scaled, or I don’t have many repositories and projects to maintain, so I never consider the README in my past experience.
So to be honest, I also just learning the importance of README, after I finally experience the hard time to learn application that doesn’t have a README. I’m totally confused and stressed. And it’s not fun! NOT FUN!
https://medium.com/media/1f83e4a733ad3206f47e6dd38aa4fc6d/href
Top comments (0)