I Built a CI and Tooling for READMEs — Lint, Regression Test, and Proofread with NLP
Let’s make README readable again!
A README helps users understand the project and facilitate collaboration between contributors.
For more details on README's best practices, please refer to my previous post.
There hasn’t yet been a lot of focus/effort on README quality due to the lack of tooling support.
Almost all programming languages have linters and static analyzers with CI platform integration. However, README/Markdown as a “programming language” does not have the same tooling support.
The CI/CD pipeline is one of the best practices for DevOps teams to implement, for delivering code changes more frequently and reliably — Isaac Sacolick
The quality of code is guarded by CI that continuously looks for defects (anti-patterns/bugs/style issues) and presents to developers with suggested fixes upon every code push to prevent quality regression in code pushes.
Like code can have bugs, a README can also have defects.
For example, a README can contain broken URL links, misspelled words, and unclear expressions making it confusing.
To avoid such issues, we ideally want someone to proofread the README every time we make a change, but a human proofreader is expansive, flaky (as standard can differ from person to person, from time to time) and not available 24/7.
A potential solution is instead of a human proofreader, let’s have a software proofreader which is. By definition, this would be a CI pipeline for READMEs.
I’ve built a CI pipeline for READMEs: readable-readme
Readable-readme is:
- Easy to set up (Almost zero configuration)
- Effortless to use (No local actions required for developers. It posts informative reports to GitHub repositories)
- Platform agnostic (Built with GitHub Action, NLP, and Node.js)
Readable-readme is a prebuilt GitHub Action that is triggered by specific events (e.g…
