Note- This is my first ever public post. Please feel free to give me constructive criticism.
Modern day web development is full of powerful, fun, and important software technologies.They come in many different configurations that can include things such as programming languages used, underlying dependencies, system architecture, licenses etc.
When a newbie developer such as myself lands on a popular web framework on Github. I am usually very overwhelmed by seeing so many folders, many files with different file formats,lockfiles et cetera. These things are different for different projects but one thing they all have in common is the README file.
I have seen README from many different projects and they all basically had the same structure. Interestingly, README is part of the GNU Coding Standards(a systematic way of writing programs), most Open Source projects are written in loose accordance with the standards. I always thought only .md or Markdown files formats work as README. But on the contrary even .txt , .me and other file formats generated by build systems can be utilized.
According to the GNU standards the release software README should have the following:-
- Package Name
- Package Version number
- General Description of package
- Installation guide
- Brief explanation of directory structure
- Copying condition(basically the license)
Most popular open source projects use this structure to tell the users about the project. Projects that use GNU build tools which follows the GNU coding standards automatically generate README with the following structure listed below. One thing to keep in mind is that this is not a strict requirement or specification. Some projects do not follow this structure but most professional ones do. Lets see if React has all of the categories covered. Click on the links it will take you to the corresponding page on React repository.
README - Yes, has a short description, version number.
Authors - Yes, facebook and thousands of individual contributors
Acknowledgements - Yes, basically thanking lot of contributers
Changelog - Yes, all the new changes in each release version
News-Yes, New releases for users is here
Install- Yes, u can also use Create a New React App(JS toolchain)
License- Yes, MIT license
Bugs- Yes, not listed as Bugs but issues sections usually talks about the bugs
Contributing- Yes
Top comments (2)
A lot of us developer just ignore the ReadMe. That is why we couldn't add something good in it. Thanks for the write up.
Thanks for reading! Yeah I agree people are busy and don't have the time to make it good. I feel like that is something beginners to coding can contribute for projects and gain experience.