Subscribe
Sign in
What makes a README file awesome?
Meow Monday ☀️
I recently enjoyed reading this Discussion on insights and best practices to get more stars on GitHub.
@zoltanszogyenyi suggested nailing the README file -- the most important of a repo? -- as it's the first thing everyone looks at.
So, what makes a README file awesome from your point of view? What are the key elements you'd expect when reading one? Any good example?
P.S. By 'awesome,' I mean a file that WOW you, that's resourceful, and makes you want to contribute.
10
Replies
@asaskevich hey Aliaksei, thanks for your reply! Love the idea of a TL,DR section at the beginning of the file.
Out of curiosity -- what are the main questions you have when you land on a new repo?
@fmerian usually at first I take a look into short description, and usage examples. If it fits my needs, I look into the Installation section and Compatibility.
In my opinion – good short description looks like these examples:
- AR Kit to build interactive views with support of 3D models
- Bitcoin client with support of Solidity smart-contracts
- Network utility which helps to diagnose egress traffic
I spent a few hours yesterday working on the README of my side project. It’s a tool called LineCoach that wants to help actors to memorize their lines. There’s a single-player aspect to it, where you have all the features needed to be efficient at memorization, but I’m also adding a collaborative aspect to it with Liveblocks.io (still working on it, lot of work left)
I checked good practices for README, but something that was missing and felt important was sharing the philosophy I’m following with the product I'm building: what are the choices I made and why. I believe that articulating your vision from the beginning will talk to some people that will understand the why, participate, stick to it and work in the same direction as you.
I want to feel the founder's vision somehow for this project/repo
@adrien_gaudon Thanks, Adrien!
I absolutely *love* this idea of adding more personality to a README fille. It would certainly help increase engagement from contributors.
Keep us posted!
Hi Flo!
A good README should have the following key elements:
1. Clear and concise description of the project's purpose and goal.
2. Detailed installation instructions with all dependencies required.
3. List of features and how to use them.
4. Explanation of the project's architecture and design.
5. Information on how to contribute to the project.
6. Explanation of the testing process and test results.
7. Documentation on how to maintain the project.
8. List of FAQs and common issues with solutions.
9. License information.
A great example of a README is the one in the official repository of the TensorFlow project (https://github.com/tensorflow/te...).
Théo
@theodore_poinsot Hey Theo, that is clear and concise -- Thanks!
What do you think of @adrien_gaudon's comment on giving more details on the *why,* for a more human, personalized approach? And what makes you contribute to an OSS project?
A good README file is essential for any open source project or software package because it provides the first impression of the project to the users. Here are the reasons why a README file can be considered "awesome":
Clear and concise language: The language used in the README file should be easy to understand, even for people who are not familiar with the project or software. Avoid using technical terms or jargon that might confuse the reader.
Well-organized structure and sections: A well-structured README file makes it easy for users to find the information they are looking for. Common sections include Introduction, Installation, Usage, Examples, Contributions, and License.
Relevant information: The README file should contain all the information that users need to get started with the project or software. This includes installation instructions, usage examples, and explanations of key features.
Relevant screenshots and images: Visual aids like screenshots and images can help users understand the project or software better.
Good formatting and links: The README file should be formatted in a way that is easy to read, with headings, bullet points, and links to other relevant resources.
Up-to-date content: The README file should be kept up-to-date, reflecting any changes or updates to the project or software. This helps users trust that the information they are reading is accurate and relevant.
for example:
# Project Name
A short description of what the project does.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Support](#support)
- [Contributing](#contributing)
## Installation
How to install the project dependencies:
npm install..
@imnikhill10 Thanks, Nikhil! And this structure example is 💎
Out of curiosity -- Do you think the License section is a must-have when you start a new open-source project? And what makes you contribute to an OSS project?
Yes, it is highly recommended to have a license for an open-source project. A license provides a legal framework for others to use, modify, and distribute the code, clearly outlining the terms and conditions under which the project can be used. This helps ensure that the code remains open-source and that contributions are properly attributed. Without a license, the default copyright laws apply, which can limit the use and distribution of the code.
for contribution part as learning developer there are several factors that can motivate them to contribute to an open-source project:
Personal interest: Contributing to a project they're passionate about or that aligns with their interests and skills.
Reputation: Contributing to a well-established open-source project can improve their reputation in the tech community and potentially lead to job opportunities.
Learning opportunities: Contributing to an open-source project can provide opportunities for developers to learn new skills and technologies.
Giving back to the community: Many developers feel a sense of responsibility to give back to the open-source community and contribute to projects that have helped them in their careers.
Collaboration: Contributing to an open-source project can be a collaborative experience, where developers can work with others from around the world to build something together.
These are just a few of the many reasons that me and other developers might choose to contribute to open-source projects.
Sequoia: Men's Sexual Wellness