Old But Not Wise
README files have been around since the 70's. Github and NPM have fueled a widespread adoption of the README file. While almost every project now contains a README file, these files are inconsistent in terms of quality and content.
Standards On The Rise
Within the Open Source community, especially within the Web/Frontend projects, there have been multiple efforts to standardize README files. These efforts each are small, and fragmented. This is mostly due to contention between maintainers (see this github issue 🌶️).
Speculation
There is a lot of value in a standard format. The Conventional Commit / Commitizen projects are a testament to this.
Most of the existing efforts, none are poised to accomplish this:
- makeareadme - more of a greatest hits page than a standard
- awesome-readme - not stringent or formulaic in its choices for quality README files
- common-readme / [art-of-readme] - only supports new projects
While standard-readme is basically just one persons opinion, I do believe the ideas are generic and sensible enough to grow into a viable standard.
Internal Usage
One major problem with the standardization efforts is the focus on libraries (specifically open source libraries). The standard is missing some key elements that an internal README would contain, mainly:
- Testing
- Deployment
There are some open source projects which resemble an internal project rather than a reusable library. Here is how a few of those match up to the standard:
| [standard-readme-spec] | react-docs | typescript |
|---|---|---|
| Title | reactjs.org | TypeScript |
| Banner | X | X |
| Badges | X | (gitter, build, azure, npm, download count) |
| Short Description | YES | X |
| Long Description | X | YES |
| Table of Contents | X | X |
| Security | X | X |
| Background | X | X |
| Install | Getting Started | Installing |
| Usage | X | Usage |
| Extra Sections | X | X |
| API | X | X |
| Maintainers | X | X |
| Thanks | X | X |
| Contributing | Contributing | Contribute |
| X | X | Documentation |
| X | Translation | X |
| X | Troubleshooting | X |
| License | License | X |
| X | X | Roadmap |
Conclusion
standard-readme, is not mature enough to do things like lint a README, and has some strange sections (License is required, and Security is a top level category???) However, it has potential to grow into an actual standard a'la Conventional Commit. If not standard-readme, I am fairly certain it will be a new project, and not a currently available alternative project.