Skip to content

Improve numerical readability scores for the tutorial. #546

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jul 14, 2025

Conversation

samcunliffe
Copy link
Member

@samcunliffe samcunliffe commented Jun 9, 2025

Inspired by @paddyroddy 's Vale talk, improving accessibility in general, and the fun of conforming fuzzy things like language into cold, hard numbers, I've made a pass at improving some numerical readability scores for the tutorial document.

In practice, this is me going through and splitting up long sentences, reducing the use of large words, and trying to say things clearly and briefly.

Anyone can play around with this themselves using:

❯ vale tutorial.md

on this branch (with the Readibility package enabled).

On the current HEAD of main:

 1:1      warning  Try to keep the LIX score       Readability.LIX
                   (47.71) below 35.
 1:1      warning  Try to keep the Automated       Readability.AutomatedReadability
                   Readability Index (11.64)
                   below 8.
 1:1      warning  Try to keep the Coleman–Liau    Readability.ColemanLiau
                   Index grade (11.12) below 9.
 1:1      warning  Try to keep the Flesch–Kincaid  Readability.FleschKincaid
                   grade level (11.87) below 8.
 1:1      warning  Try to keep the Gunning-Fog     Readability.GunningFog
                   index (13.52) below 10.
 1:1      warning  Try to keep the SMOG grade      Readability.SMOG
                   (13.25) below 10.
 1:1      warning  Try to keep the Flesch reading  Readability.FleschReadingEase
                   ease score (46.86) above 70.

On the HEAD of this branch:

 1:1     warning  Try to keep the LIX score       Readability.LIX
                  (39.32) below 35.
 1:1     warning  Try to keep the Coleman–Liau    Readability.ColemanLiau
                  Index grade (9.86) below 9.
 1:1     warning  Try to keep the Flesch–Kincaid  Readability.FleschKincaid
                  grade level (8.73) below 8.
 1:1     warning  Try to keep the Gunning-Fog     Readability.GunningFog
                  index (10.73) below 10.
 1:1     warning  Try to keep the SMOG grade      Readability.SMOG
                  (11.24) below 10.
 1:1     warning  Try to keep the Flesch reading  Readability.FleschReadingEase
                  ease score (57.70) above 70.

All numbers are better, though most are still "warning" level (we only lost the ARI).

Now! I'm aware this is coming very close to the tutorial delivery (sorry!!). So we might want to wait on merging this until afterwards. I leave it up to you @Saransh-cpp. You're the workshop lead...

@samcunliffe samcunliffe changed the title ... Improve numerical readability scores for the tutorial. Jun 9, 2025
@samcunliffe samcunliffe marked this pull request as draft June 9, 2025 15:27
@samcunliffe samcunliffe requested a review from Copilot July 14, 2025 10:50
@samcunliffe samcunliffe marked this pull request as ready for review July 14, 2025 10:50
Copy link
Contributor

@Copilot Copilot AI left a comment

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 updates the tutorial to improve readability by simplifying language and rephrasing steps, and it enables the Vale Readability checks.

  • Simplified and restructured tutorial sentences for clarity and brevity
  • Added Vale Readability style to .vale.ini
  • Cleaned up formatting and links in the tutorial

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File Description
tutorial.md Reworded steps and tips, improved flow, and added concise phrasing
.vale.ini Added Readability package to enforce readability metrics in Vale scans
Comments suppressed due to low confidence (1)

tutorial.md:286

  • [nitpick] Clarify this instruction by specifying the actual prompt indicator, for example: 'you should see (.venv) or (your_env_name) on the left of your terminal prompt'.
So activate your environment and you should see braces `( )` with your project slug on the left of your terminal window.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@samcunliffe samcunliffe self-assigned this Jul 14, 2025
@samcunliffe samcunliffe added documentation Improvements or additions to documentation enhancement New feature or request accessibility Something relating to the ease of accessibility (alt-text, colour choices, language, etc) labels Jul 14, 2025
@samcunliffe
Copy link
Member Author

(tagging @matt-graham and @paddyroddy: feel free but under no obligation to join the review)

Copy link
Member

@Saransh-cpp Saransh-cpp left a comment

Choose a reason for hiding this comment

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

Thanks, @samcunliffe!! I went through the whole thing (while practising for tomorrow) and it looks great. I'll merge this in right now for tomorrow.

@Saransh-cpp Saransh-cpp merged commit 1558a87 into main Jul 14, 2025
15 checks passed
@Saransh-cpp Saransh-cpp deleted the sc/improve-numeric-readability-scores-tutorial branch July 14, 2025 21:38
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 enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants