In the wake of the we’ve seen a huge growth in open source contributions. The open-source community has opened over 400 000 pull requests during October alone. That’s insane! Hacktoberfest I started looking into projects with large amounts of contributions. It got me thinking. A common pattern started appearing. They all have amazing readme.md files. I doubt it would have been easy to contribute otherwise. There may be a connection. I’d sure say there is! Let’s mention a few famous projects like , , , or You can see their readme.md’s are a perfect blend of documentation, project overview, FAQ, and contribution steps. They mention the ecosystem, the community, and have visuals explaining the open source project itself. React Vue freeCodeCamp Sourcerer Serverless. Because the open-source community runs the project, it needs a central file to make communication easy. It’s a file where maintainers explain all project details, as a guide. But what exactly is a readme.md file? What’s a readme? The pillar of any open source project is the readme.md. It contains all necessary information for understanding the direction the project is heading. It explains the software and its purpose. Any prerequisites are also there to make sure new contributors can get up to speed quickly. The most important part is that it contains steps to get the software running on your local machine for development purposes. But, it should also contain steps to deploy the software to production as well. Why do you need a readme? When you want people to notice you and your work, don’t you use a resume, a GitHub profile, or even a website? Well, of course, you do. So do I. The same logic applies to an open-source project. The readme.md is your software’s resume. Add anything you think will make it easier to understand for future contributors. It’s quite sensible you should first create a readme.md before going public with a project. It’ll make your life as a maintainer or collaborator infinitely easier. Answering questions and helping contributors will become a walk in the park. That’s why you should make a habit of making it the first file you create in a project. Make sure to place it in the root directory of your project, so it’ll be visible on GitHub. How to write a readme? Luckily, you don’t need to reinvent the wheel. There are a few awesome templates you can use. What you need to keep in mind is to have a natural flow in your readme.md. You want it to be easy to understand and simple to start collaborating for everyone who reads it. Take a look at this amazing template by . It’ll get you up and running in no time. Billie Thompson But, there are a few things missing. First of all, ways of engaging the community more. Feel free to add visuals, badges, images, videos, and even GIFs to your readme.md files! Don’t forget, your goal is to get people to love your project. You can’t forget to give contributors a sense of appreciation for helping out. Here’s where comes in. It’ll walk you through the whole process of writing an awesome readme.md. Make A Readme www.makeareadme.com Make a README If you have run out of energy or time for your project, put a note at the top of the README saying that development has… Remember, the key takeaways are to engage the community and appreciate contributors. First, start by adding badges. I love badges! You use them to show build status, test coverage, PR status, vulnerabilities, and what license you’re using. Be bold with these, because they’ll make your project look serious. Social proof is everything in the open-source community. And the best part, you can . Or, copy the ones below. 😉 create your own Another awesome tool that bridges the gap between awesome visuals and appreciating your contributors is . Hall of Fame github.com sourcerer-io/hall-of-fame trophy: Show some love to your contributors! A widget for your repo README. Visual and clean. Refreshes every hour. … Mentioning people who built the software is a major step toward getting the community engaged. Let’s be honest, wouldn’t you want to see yourself as a contributor to an awesome open-source project!? I sure would. Did I miss anything? What if your project starts growing at an increasing rate? Then you should start thinking about creating a contributing.md. It’s where you put all details about contributing and pull requests. It acts as the official guide for all open-source lovers on how to start contributing to your project. Here’s how it looks for freeCodeCamp. github.com freeCodeCamp/freeCodeCamp The https://freeCodeCamp.org open source codebase and curriculum. Learn to code for free together with millions of… It doesn’t stop there. First, add a license.md for specifying the level of openness. Then, a code_of_conduct.md to explain general rules and conditions developers should act by. In the end, we should all be awesome to each other. The code of conduct is there to make sure we are. Wrapping up Every awesome open-source project has an amazing readme.md, and it makes perfect sense. We, humans, have limited attention spans. We need a readme.md that to get potential contributors to start creating pull requests. By looking at repositories like or , you can see a common pattern. Clear explanation of features, content, documentation, contributing guidelines, and engaging visuals. pops freeCodeCamp Sourcerer In the end, you don’t need to reinvent the wheel. Use templates. Follow the guidelines above. Engage your community and be awesome towards your fellow developers! That’s what it’s all about. Helping each other create amazing software to benefit humanity. If you want to check out one of my previous personal growth related articles, feel free to head over to , or check it out below. my profile medium.freecodecamp.org How to pimp out your developer profile and leave your old résumé in the dust In this article, we’ll discuss how to pimp up your developer profile in a few short steps. Hope you guys and girls enjoyed reading this as much as I enjoyed writing it. Do you think this tutorial will be of help to someone? Do not hesitate to share. If you liked it, smash the clap below so other people will see this here on Medium.

A crash course on writing a better README

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

A crash course on Serverless APIs with Express and MongoDB

102 Stories To Learn About Open Source Software

10 Repositories that Will Transform the Way You Approach Technical Interviews

10 Python Projects with 10 Lines of Code

10 GitHub Repositories to Follow

A crash course on Serverless APIs with Express and MongoDB

102 Stories To Learn About Open Source Software

10 Repositories that Will Transform the Way You Approach Technical Interviews

10 Python Projects with 10 Lines of Code

10 GitHub Repositories to Follow

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps