Improve numerical readability scores of our README #590

samcunliffe · 2025-09-18T14:04:44Z

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

…bout 'just'.

samcunliffe · 2025-09-18T14:06:16Z

README.md

-[discussions](https://github.com/UCL-ARC/python-tooling/discussions) for this
-repo, and we welcome questions there or in the `#helpme` channel on the
-[UCL research programming hub Slack](https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub).
+This repository collects our recommendations for a research software project in Python.


I got rid of [UCL ARC] because our name is already in the title up on line 4, and in the repo header in GitHub's UI.

Copilot

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.}

README.md

paddyroddy · 2025-09-30T08:53:48Z

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

Some thoughts

README.md

@paddyroddy

Overruled by Vale and @paddyroddy. Co-authored-by: Copilot <[email protected]>

Co-authored-by: Patrick J. Roddy <[email protected]>

samcunliffe · 2025-10-08T12:10:30Z

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...)

dstansby · 2025-10-08T12:24:23Z

README.md

-repo, and we welcome questions there or in the `#helpme` channel on the
-[UCL research programming hub Slack](https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub).
+This repository collects our recommendations for a research software project in Python.
+We have a [website] if you need some advice, and a template if you're starting from scratch.


This is vague, advice for what? And starting what from stratch?

advice for what?

Python tooling?

And starting what from stratch?

a research software project in Python. (the subject of the preceding sentence, pretty sure that's legal)

This repository collects our recommendations for a research software project in Python. # Unchanged We have a [website] if you need some advice for what tools to use, and a template if you're starting a project from scratch.

This feels redundant (to me) but does improve the three remaining readability scores slightly. Is that OK?

dstansby · 2025-10-08T12:24:42Z

README.md


-🍪 Our template is a [cookiecutter] template which automatically creates new
-Python packages with our recommended tooling set up and ready to go.
+🍪 Our template uses [cookiecutter] to set up a new package with our preferred tools ready to go.


Suggested change

🍪 Our template uses [cookiecutter] to set up a new package with our preferred tools ready to go.

🍪 Our template uses the [cookiecutter] tool to set up a new package with our preferred tools ready to go.

dstansby · 2025-10-08T12:25:03Z

README.md

-> If you're making a package within a community that has an existing
-> package template (e.g., [`SciKit-Surgery`](https://github.com/SciKit-Surgery/PythonTemplate)),
-> we recommend using their template instead of this one.
+> If you're making a package in a research community that already has a template, use theirs instead!


I think it's worth keeping an example here of a community that uses a specific/different template.

This was a deliberate change.

The parentheses and abbreviation (e.g.) decrease readability. And I wasn't too enthusiastic about the specific example.

dstansby · 2025-10-08T12:26:09Z

README.md


-Some quick instructions for using our template are below.
-We also have a longer [tutorial](./tutorial.md) that has been presented in workshops for researchers at UCL.
+If you're comfortable with the command line, here are some quick start steps.


What if you're not comfortable with using the command line?

Suggested change

If you're comfortable with the command line, here are some quick start steps.

Here are some quick start steps. We assume you're already familiar with using the command line.

Lol. Good point.

Your suggestion reduces readability (although I agree that it's good). If we drop the second sentence, the scires are much better:

Here are some quick start steps.

That works, right?

README.md

dstansby · 2025-10-08T12:28:03Z

README.md

+It will have created a directory for your project:
+
+```sh
+ls -ltr | tail -n1  # Show the last directory that was created


I find the number of non-exapanded flags in this command a bit overwhelming (but appreciate it's a hangover from before this PR, so doesn't need to be improved here)

It looks like:

ls -lt --reverse | tail --lines=1

(-l and -t don't have expansions)

Is that better?

dstansby · 2025-10-08T12:28:33Z

README.md

+- change directory to your project directory,
+- initialise a `git` repository,
+- and _install_ your new package editable mode.


Should this be an ordered (numbered) list, since it has to be done in the specific listed order?

Suggested change

- change directory to your project directory,

- initialise a `git` repository,

- and _install_ your new package editable mode.

1. change directory to your project directory,

2. initialise a `git` repository,

3. and _install_ your new package editable mode.

samcunliffe added 3 commits September 18, 2025 14:11

First pass.

ad567bf

More improvements. Some suggestions from copilot.

371f88b

Typo and delete a 'just'. The Carpentries people would not be happy a…

c212066

…bout 'just'.

samcunliffe commented Sep 18, 2025

View reviewed changes

samcunliffe requested a review from Copilot September 18, 2025 14:06

Copilot AI reviewed Sep 18, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

samcunliffe requested a review from a team September 18, 2025 14:08

samcunliffe self-assigned this Sep 18, 2025

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 requested changes Sep 30, 2025

View reviewed changes

README.md Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

samcunliffe and others added 2 commits October 8, 2025 13:07

Lowercase for consistent name "cookiecutter"

523ed25

Overruled by Vale and @paddyroddy. Co-authored-by: Copilot <[email protected]>

Ruff-compliant space before comment.

67397fc

Co-authored-by: Patrick J. Roddy <[email protected]>

samcunliffe requested review from a team and paddyroddy October 8, 2025 12:08

dstansby reviewed Oct 8, 2025

View reviewed changes

Merge branch 'main' into sc/numerical-readability-of-README

9a8f9e5

	🍪 Our template uses [cookiecutter] to set up a new package with our preferred tools ready to go.
	🍪 Our template uses the [cookiecutter] tool to set up a new package with our preferred tools ready to go.

	If you're comfortable with the command line, here are some quick start steps.
	Here are some quick start steps. We assume you're already familiar with using the command line.

Improve numerical readability scores of our README #590

Are you sure you want to change the base?

Improve numerical readability scores of our README #590

Uh oh!

Conversation

samcunliffe commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

paddyroddy commented Sep 30, 2025

Uh oh!

paddyroddy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samcunliffe commented Oct 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samcunliffe Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samcunliffe Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

samcunliffe commented Sep 18, 2025 •

edited

Loading

samcunliffe Oct 8, 2025 •

edited

Loading

samcunliffe Oct 8, 2025 •

edited

Loading