What is the key to a system or product that is attractive? It all starts with the all-important readme. The README is the first page of your project – it's usually the first impression you make to users and contributors.
A good readme should give users an idea of what the project is about, the language used, the terms and conditions, what your project can do, screenshots showing the running application, etc. The user of the readme file could be a recruiter, your future boss, or a client. Therefore, it is important to note that the project's readme should include the what, why, and how of the project. It is important to clearly describe the purpose, function, how to use, installation steps, and other information of your project or product. Make sure your readme file is easy to read and understand, and provide useful information to users or other developers, as well as links and further instructions that may not be appropriate for the readme file to avoid searching through all other files unnecessarily. This can cause users to lose interest and move on to the next potential employee.
Writing a good project readme is very important and I can't stress it enough. Not only are users looking for information about the project itself, but they can also see your documentation skills and attention to detail, which can make it easier for you to get a job.
If you've read my other articles, you've probably noticed how important it was to my career to learn other skills besides programming that ultimately helped me get a job. Good documentation is one of them. Here are some guiding questions to help you: What is the project about?
Why did you develop it and what was your motivation?
What problem does it solve?
What have you learned?
What makes your project stand out?
I'm going to show you how to convert these questions to text. Description:The purpose and description of the project so that people reading your portfolio can understand the project within the first few seconds of reading the project information. Tech stackThe tech stack includes the programming languages, libraries, and frameworks used by your project (e.g., python, react, etc.). If you have a front-end application that uses an external public API, please mention this.
The user interface related to the projectDesign examples. If your project has a user interface, you can insert a gif, **, or image of the user interface.
If it's an app that runs on a terminal, you can create a GIF to show how to use it. This helps to understand how to interact with the application and what people will see when they run the project. GIFs and other visuals can never replace the work of providing specific details in a document, but they can definitely provide an extra element of "wow" when showcasing a project's user interface. They allow readers to easily and quickly access a wealth of information about the project, which is key to increasing adoption and ultimately contributing to the project.
featuresIf your project has a lot of features, you should add themfeaturessection and list them here.
How to run the projectInstructions on how to set up, run, and use your project. If someone wants to start the project from scratch, that's fine, they should find everything they need to know in the project's readme file without any help from you. If it's simple, you can include it in the readme. If the description is longer, you can also add a description file to the reference project.
You should also use Netlify to host your project so that users can open the deployed app and use it immediately to see how it works. (Keep in mind that not every recruiter who looks at your GitHub profile has a good understanding of how to build a project locally.) ) to create a readmeMD files represent Markdown, a lightweight markup language with a simple text formatting syntax. It's a very simple language for creating beautiful and aesthetically pleasing readme files for GitHub. As a result, you can use the typical Markdown language.
Here are two examples of beginner projects that I applied for a job for three years ago.
There is no single criterion for a good README, and every project has different goals and expectations. Here are some readme papers for different types of projects.
npm is the most popular j**ascript package manager. Given that this is a package manager, it's hard to explain the project visually. The project does a great job of keeping the readme itself simple, very relevant, and links to more complex and detailed information.
The lar**el readme provides a lot of links to documentation, but more importantly, it provides links to community learning resources. These include Lar**el Bootcamp, which shows you how to get up and running quickly, and Laracasts, a comprehensive library of tutorials. According to the developers, these resources are one of the most appreciated aspects of Lar**el, so it's important to communicate this to potential users as early as possible (i.e., in the readme).
vscode is everywhere, and it also has a great readme. It shows what the IDE looks like during use, so users can immediately understand what the product is. These products are more mature and easier for developers to understand than in-house tool developers like Appsmith, so they don't necessarily need more visualizations. VSCode provides a short, to-the-point description of the product with links to more detailed information.
Trekhleb's Homemade Machine Learning, a project that focuses more on education than on products. Machine learning can be very complex to learn, so projects like this can benefit from good visualizations and links. This project makes full use of visualizations to help students form a mental model in the field of machine learning, which involves a considerable amount of knowledge. There are a lot of different algorithms to learn, but once you have them in mind, there's a logical way to classify them, and this diagram illustrates that well.
Original link: This article has been translated and published.