The State of README Standards
Publish Date2019-09-18

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:

  1. Testing
  2. 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.