Introduce Readable Readme
A CI/CD pipeline to help maintain high-quality docs
In software engineering, code readability is essential for keeping a project maintainable.
To achieve code readability, tools like static analyzer and linter (e.g. TSLint, DeepScan, and DartAnalyzer) were developed.
By contrast, though documentation is equally important, the focus on documentation readability is lacking.
Readable Readme is an NLP based documentation analyzer
To fill in the gap, I built Readable Readme, an automated documentation static analyzer plus linter, and here is how it works:
Readable Readme is built with:
- GitHub Actions
- TypeScript
- Rule-based language analyzer
- Deep learning-based language analyzer
Readable Readme uses GitHub Action for better reusability
To add Readable Readme into your repository, simply create a .github/workflows/readable-readme.yml with the following content:
Once the workflow configuration above is added, upon workflow triggering (e.g. code pushes, pull requests), Readable Readme will generate a report with issues and suggested fixes:
Clicking on a report expands the full report:
The full report of a documentation file looks like:
As of the writing of this article, Readable Readme supports grammar checking with a rule-based analyzer and sentiment analysis with NLP neural network as shown above.
Let’s make README readable again together!
If you like the idea of Readable Readme:
- Follow the Readable Readme Publication and me (maybe?) ;)
- Star the Readable Readme Repository (linked below)
- Subscribe to the newsletter for the latest updates
