About: 👋 Selftaught Accessibility & Frontend Developer
💻 Dev & UX Accessibility Specialist @Atos | CPACC
🙆 Improving the world with accessible web content
✍️ Content creator, Tips on How To Get Into Tech
Location:
Vienna, Austria
Joined:
May 11, 2020
How to create a good README.md file
Publish Date: Feb 9 '24
459 56
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")
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.
This app will help abandoned animals get help from Animal welfare organizations all over the world when people reporting them via this app.
Description
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. 🥳
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.
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.
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.
🏆Congratulations $750🏆 💥 Get your money from here 👇❤️ WAITING 2 minutes💥
👇👇𝐂𝐚𝐬𝐡💵💵💥 👇❤️ 🇺🇸 Only USA 🇺🇸❤️👇sites.google.com/view/work-from-ho...
all process complete then check email
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) :)
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
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 ;-)
SPEAK WITH HIM TO ASSIST YOU WITH PROFS. Having a cheating partner is disgusting. It’s really terrible for anyone to bear a cheating partner. The best way to handle these suspicions is to do everything in your power to catch them, preferably in the act. My SPOUSE was cheating and had always gotten away with it because I did not know how as I was always too scared to pin anything on her. I went in search of a hacker who could break into cell phones without any trace and I ran into a very strong and reliable hacker called 5ISPYHAK. I quickly reached out to him to satisfy my curiosity. Within a few minutes I got a response from him asking me which of his services I was interested in. I explained my worries to him. He requested for certain details which I did not hesitate to provide because he promised me his services were a hundred percent satisfactory. Few hours after our initial conversation a notification popped in and it was all the information I wanted. My heart was really broken to find out that my wife was indeed cheating with my brother. I knew that she was cheating but I didn’t know with someone close to me. All thanks to THE RECOMMENDATION OF 5ISPYHAH his services and went on to file for a divorce. email him at:
I recently had a terrible experience with bitcoin scamming. I was scammed out of my entire cryptocurrency portfolio, and it felt like all hope was lost. But then, I heard about 5ispyhak from some of my friends who recommended the professional hacker for their services. After doing more research on them, I decided to give them a try and contact them via email at 5ispyhak437@gmail.com . To my surprise, they were able to recover almost all of the funds that were stolen from me! It seemed too good to be true but they delivered on their promise in an incredibly short amount of time - less than 24 hours! They provided detailed instructions throughout the process which made it very easy for me understand what steps needed to be taken in order for everything go smoothly without any issues or delays along the way. Overall, this experience has been nothing short of amazing thanks largely due to 5ispyhak’s professionalism and dedication towards helping people get back what rightfully belongs theirs - no matter how difficult or complexed it may seem at first glance! If you ever find yourself in a similar situation as mine where your cryptocurrencies have been stolen away by scammers online then don’t hesitate reach out these guys as soon as possible so that you can start recovering your losses immediately before its too late!.
🏆Congratulations $750🏆 💥 Get your money from here 👇❤️ WAITING 2 minutes💥
👇👇𝐂𝐚𝐬𝐡💵💵💥 👇❤️ 🇺🇸 Only USA 🇺🇸❤️👇sites.google.com/view/work-from-ho...
all process complete then check email
🏆Congratulations $750🏆 💥 Get your money from here 👇❤️ WAITING 2 minutes💥
👇👇𝐂𝐚𝐬𝐡💵💵💥 👇❤️ 🇺🇸 Only USA 🇺🇸❤️👇sites.google.com/view/work-from-ho...
all process complete then check email
Embarking on the exciting world of cryptocurrency investment, I took a leap of faith and allocated a significant sum of money, 110,000, into Bitcoin. However, what was supposed to be a promising venture turned into a nightmare when I found myself facing a devastating loss. The emotional toll and financial impact were immense, leaving me desperate to find a solution. This is the story of how I discovered TRUSTGEEKS HACK EXPERT, a team of tech experts who helped me reclaim my lost funds and restore my hope in the face of adversity. Looking back, buying Bitcoin seems like a great idea. It was the buzz of the town, and the promise of huge profits had me daydreaming about an early retirement on a tropical island. I so took the risk and made a sizable investment in this illusive digital currency, a combination of exhilaration and naivete. In times of need, drastic actions are necessary, and I was prepared to do whatever it took to recover my losses. While searching the internet for answers, I came upon a ray of hope among the many con artists and misleading claims. TRUSTGEEKS HACK EXPERT, a well-known tech firm that specializes in retrieving lost money from cryptocurrency scams and fraudulent investments, provided that glimpse of hope. After weeks of hard work and collaboration with TRUSTGEEKS HACK EXPERT, the moment I had been desperately waiting for finally arrived. I received the incredible news that my lost funds were successfully retrieved. It was a monumental milestone in my life, one that called for a celebration like no other. Finally, I could breathe a sigh of relief and put this nightmare behind me. It's impossible to describe the emotional rollercoaster I went through during this encounter. It seemed as though I had gone through the mill, going from rage and irritation to fear and anxiety. However, a feeling of relief overcame me as soon as I was informed that my recovery was successful. It served as a timely reminder that optimism always lingers, even in the most dire circumstances. I felt in control again and had overcome difficulty in addition to getting my lost money back. You can get in touch with them through their email address at. trustgeekshackexpert@fastservice.come & Telegram: @Trustgeekshackexpert, I realized that there were several factors that contributed to my unfortunate loss. Impulsivity and a lack of research played a significant role in falling for the scam. My eagerness to make quick money clouded my judgment, and I failed to recognize the warning signs. It was a valuable lesson in the importance of conducting thorough due diligence before diving headfirst into any investment opportunity. In brief, losing a sizable sum of money on an investment in bitcoin was definitely a crushing blow. The bright spot in this gloomy situation, though, turned out to be TRUSTGEEKS HACK EXPERT help. When all appeared lost, their knowledge, demeanor, and spirit of cooperation gave me hope. Even while the path to financial recovery was not simple, this amazing IT team's humor, charisma, and unwavering pursuit of justice made it bearable.
Having a cheating husband is one of the worst thing to experince in a marriage. you keep up with your best and yet get disappointed . i have been married for more than 8 years now but for the past 2 months my husband started coming back late night , takes late night calls, and restricted me from touching his phone so i was worried and advised to get a hacker so i checked online for the best and i was recommended [ Spyrecovery36 @gmail. com ] to be the trusted hacker. After following his instructions , i got access to his phone through a link without touching his phone physically , now i got to know the truth.
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.
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.
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.
Fantastic guide on crafting an effective README.md file! Your seasoned advice and structure tips showcase your expertise. Gratitude for sharing these invaluable insights.
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!
Great blog post.
Suggestion -
Get the hands-on experience with the visual look and feel based mark down editor? use the below options.