Hey beginners,
Congrats on making your way to open source. It?s a great community.
It?s a bit confusing in the starting. How to contribute, where to contribute, issues, bugs, PR, PR, PR!
Don?t worry, as you get yourself involved in open source you?ll learn it all.
But today I?d like to give you all some advice which I never received when I started my open source journey.
I started contributing to open source and putting all my tiny side projects on GitHub a while ago. Back then I didn?t know about the README part. Time passed and I started following some kickass developers. No doubt they all had amazing projects but the one most common thing was, all their projects had awesome README and that?s how I came to know about the importance of a good README.
STOP!! I?m not interested in reading about your open source journey. Just tell me about how to write a good README.
Cool. So here you go ?
Before you start putting your awesome projects on GitHub, I want you to go and read about Readme Driven Development first.
Why should I care about a README?
Open source community is growing rapidly. Developers release new open-source projects on GitHub every day. As a result, it?s becoming more and more difficult to get your own project to stand out from the sea of open-source software. However, you can do a few things to increase your chances of grabbing other developer?s attention. One effective and simple technique is putting up a nice-looking and helpful README file.
Your README should be as good as your project. A great README file helps your project to stand out from the sea of open-source software on GitHub.
A README is like the face of your project. It is the first file a person should read when encountering a source tree, and it should be written as a very brief and giving very basic introduction to the software.
A project without README is not so useful. Let?s take a look at this project, for instance.
No README, no description, no nothing. You won?t get any idea what this guy built, no matter how awesome it is.
Now let?s take a look at this project. The author has mentioned detailed and clear instructions about the project and hence easier for others to use and try it out.
A nice README is a good way to help people engage in the project as well. A project with nice README and screenshots will get the attention of users better since it?s a direct way to explain why this project matters, and why people should use and contribute to the project. Good README should also include enough details to help a new user get started, e.g. how to compile, how to install, and how to start integrating.
Ok. Enough talk. Show me how to write a good README then.
Now as you agree that README matters, I?ll tell you how to write one. It?s not so difficult. You just need to stick with some bullet points. Here are some of the points you should keep in mind while writing a README.
Formatting of README?
Now that you have taught yourself how and what to write in a README, let?s talk a bit about the styling of README aka formatting.
Formatting is an essential part of README. You can learn about how to format your README from here and here.
In the end, Keep in mind ?
You don?t need to go full-bore Readme Driven Development, you don?t need to include all those bullet points , you don?t need to follow any particular process. But writing a good README will definitely improve your documentation skills which will make you a better developer.
You can check out some of the examples and resources which will help you in writing a good README.
akashnimare/foco
Stay focused with foco :rocket: [WIP]
github.com
sindresorhus/pageres
pageres – Capture website screenshots
github.com
noffle/art-of-readme
art-of-readme – :love_letter: Learn the art of writing quality READMEs.
github.com
matiassingers/awesome-readme
awesome-readme – A curated list of awesome READMEs
github.com
dbader/readme-template
readme-template – README.md template for your open-source project
github.com
jehna/readme-best-practices
readme-best-practices – Best practices for writing a README for your open source project
github.com
The Most Important Code Isn’t Code
Documentation is the single most important change I’ve made to my coding style in the last year. I’m not talking about?
zachholman.com
That?s it. You?re ready to rock-n-roll in open source world ?
Thanks for reading. If you are just starting out your open source journey, you should checkout my other article about my development setup here. If you have any question or need any help, feel free to contact me here @meakaakka.
If you liked this post, please consider clapping for it. I notice each one and appreciate them quite a lot. Thank-you!
