Skip to content

Improve numerical readability scores of our README - #590

Merged
samcunliffe merged 11 commits into
mainfrom
sc/numerical-readability-of-README
Sep 16, 2026
Merged

samcunliffe merged 11 commits into
mainfrom
sc/numerical-readability-of-README

Conversation

@samcunliffe

@samcunliffe samcunliffe commented Sep 18, 2025

Copy link
Copy Markdown
Member

Following on from #546, I've reworded our README, using vale's Readability suite.
I don't think there's a nice way to get vale to make a comparison of values between two commits (@paddyroddy?), so here's a manual comparison table (which I hope is helpful, because it was very boring to make!)

Advice Before (1ddd9b8) After (c212066)
Keep the Flesch reading ease score above 70. 56.42 🔴 64.17 🔴
Try to keep the LIX score below 35. 43.12 🔴 39.78 🔴
Try to keep the Coleman–Liau Index grade below 9. 10.19 🔴 9.20 🔴
Try to keep the Flesch–Kincaid grade level below 8. 9.10 🔴 < 8
Try to keep the SMOG grade below 10. 11.10 🔴 < 10
Try to keep the Automated Readability Index below 8. 8.45 🔴 < 8
Try to keep the Gunning-Fog index below 10. 10.20 🔴 < 10

You can check these yourself with:

cd /place/where/this/repo/is
vale sync
vale README.md

Comment thread README.md
@samcunliffe
samcunliffe requested a review from Copilot September 18, 2025 14:06

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR improves the numerical readability scores of the README by simplifying language and restructuring content. The changes aim to make the documentation more accessible while maintaining all essential information.

Key changes:

  • Simplified language and shortened sentences throughout the README
  • Restructured sections with clearer headings and better organization
  • Added a dedicated "Need help?" section for support information

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

Comment thread README.md Outdated
@samcunliffe
samcunliffe requested a review from a team September 18, 2025 14:08
@samcunliffe samcunliffe self-assigned this Sep 18, 2025
@samcunliffe samcunliffe added documentation Improvements or additions to documentation needs-2-reviewers Could be considered "controversial" so worth a second pair of eyes accessibility Something relating to the ease of accessibility (alt-text, colour choices, language, etc) labels Sep 18, 2025
@paddyroddy

Copy link
Copy Markdown
Member

I don't think there's a nice way to get vale to make a comparison of values between two commits

I highly doubt it. We could do it in our own way fairly easily, but vale isn't centred around the Readability rule.

@paddyroddy paddyroddy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some thoughts

Comment thread README.md
Comment thread README.md Outdated
Comment thread README.md Outdated
samcunliffe and others added 2 commits October 8, 2025 13:07
Overruled by Vale and @paddyroddy.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com>
@samcunliffe
samcunliffe requested review from a team and paddyroddy October 8, 2025 12:08
@samcunliffe

Copy link
Copy Markdown
Member Author

Cheers, Paddy! I've re-requested a review from @UCL-ARC/collaborations-python-tooling to get a second.

@matt-graham and @dstansby, you both wrote earlier versions of this, so your opinions are gratefully received. (If you have the capacity to review...)

Comment thread README.md Outdated
Comment thread README.md
Comment thread README.md
Comment thread README.md Outdated
Comment thread README.md
Comment thread README.md Outdated
Comment thread README.md Outdated
@samcunliffe

Copy link
Copy Markdown
Member Author

I will update this. It's been ages but still feels worthwhile.

@matt-graham matt-graham left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This all looks great to me, thanks @samcunliffe for picking this up again.

@paddyroddy paddyroddy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👌

@samcunliffe
samcunliffe merged commit fe96c99 into main Sep 16, 2026
17 checks passed
@samcunliffe
samcunliffe deleted the sc/numerical-readability-of-README branch September 16, 2026 08:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

accessibility Something relating to the ease of accessibility (alt-text, colour choices, language, etc) documentation Improvements or additions to documentation needs-2-reviewers Could be considered "controversial" so worth a second pair of eyes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants