-
Notifications
You must be signed in to change notification settings - Fork 6
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
Improve numerical readability scores for the tutorial. #546
Conversation
…adability-scores-tutorial
for more information, see https://pre-commit.ci
There was a problem hiding this 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>
(tagging @matt-graham and @paddyroddy: feel free but under no obligation to join the review) |
There was a problem hiding this 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.
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:
on this branch (with the
Readibility
package enabled).On the current
HEAD
ofmain
:On the
HEAD
of this branch: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...