What makes a README file awesome?

Question

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.

Théodore Poinsot · Accepted Answer

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

Aliaksei Saskevich · Answer

I'll be short - README is like CV - it should be short, structured and contains main answers at the beginning of the file, so reader can catch main questions and ideas in no time!

Adrien Gaudon · Answer

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

Aliaksei Saskevich · Answer

@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

flo merian · Answer

@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?

flo merian · Answer

@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?

flo merian · Answer

@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?

Nikhil Sharma · Answer

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.

flo merian · Answer

@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!

What makes a README file awesome?

Replies