search

pyOpenSci / python-package-guide

scientific Python package recommendations & guidance curated by pyOpenSci
https://www.pyopensci.org/python-package-guide/
Other
93 stars 51 forks source link

remove `write-good` #317

Open sneakers-the-rat opened 1 month ago

sneakers-the-rat commented 1 month ago

went to commit and had an error in vale and wondered what it was, started looking at the rules, reading the write-good module and was like "surely not" so I enabled it and ran it and it spit out like a thousand warnings and errors. I'm aware that it isn't enabled, but here is a sample:

package-structure-code/publish-python-package-pypi-conda.md
 5:67     warning  'be installed' may be passive   write-good.Passive
                   voice. Use active voice if you
                   can.
 16:6     warning  'minimize' is too wordy.        write-good.TooWordy
 26:189   warning  'in order to' is too wordy.     write-good.TooWordy
 32:71    error    Don't start a sentence with     write-good.ThereIs
                   'There is'.
 34:1     warning  'prior to' is too wordy.        write-good.TooWordy
 36:1     warning  'Many' is a weasel word!        write-good.Weasel
 36:38    warning  'be found' may be passive       write-good.Passive
                   voice. Use active voice if you
                   can.
 40:25    warning  'it is' is too wordy.           write-good.TooWordy
 40:28    warning  'is written' may be passive     write-good.Passive
                   voice. Use active voice if you
                   can.
 41:1     warning  'only' is a weasel word!        write-good.Weasel
 54:23    warning  'really' is a weasel word!      write-good.Weasel

these errors are because the rules for write-good literally are configured to issue a warning on the mere presence of a pretty large list of words, eg.: https://github.com/pyOpenSci/python-package-guide/blob/main/vale-styles/write-good/Weasel.yml

The rule that is enabled, for switching the capitalization of PyPI in markdown, makes perfect sense (although it makes me sad that the state of software is such that tools like ruff aren't flexible enough to be able to add a rule as simple as that so we have to download 82MB of binaries to correct capitalization). No problem with that.

in addition to this ruleset being annoying, i think it's also something that we shouldn't have in the repo because it represents something imo we should run far away from as an org. part of what i love about this group is how very human, informal, sometimes even improvisational it is - a breath of fresh air in programming world. a big part of that is the style of our prose, and how our entire everything is very DIY and reflective of the many hands that went into it. the idea of a prose linter is intrinsically grating to me - language is not the same as code, language is a fuzzy, messy, expressive system, and our voice is a direly important part of who we are as people. the writing style of these docs in particular is vibrant and chaotic and caring and oh so so human, we should not do anything that would make us lose that in my opinion.

This set of rules reflects a sort of machinelike uniformity that - to maybe be pejorative for a second - screams of a tech bro who simply does not understand how language works. Making linter rules that detect the mere presence of words without considering how no word ever exists in isolation, and might just be part of the way someone expresses themselves instead of being a weasel word worthy of a warning, is reflective of an ideological stream in software i think we should keep far away from.

Even though it's disabled, i think we should remove this directory vale-styles/write-good because it is not reflective of the values of mutual empowerment that i believe we in this organization embrace. Not to be too dramatic.

Tagging @flpm - i missed the conversation but am 100% positive that his intentions here were just to show a cool tool (in the original very well described pull request he describes it explicitly as just being an example of what rules can do) and not to police language - just wanted to make sure there wasn't a surprise if we decide to remove it since he was the one that added it. no harm no foul here i just think we shouldn't have stuff like this in our code <3

flpm commented 1 month ago

This makes sense, when I tried vale there were so many issues that I even decided to disable the internal vale checks.

It's a bit annoying that every time vale runs for the first time, it downloads the binary. If we end up not using more functionality than simple substitutions we can keep eye open for other, simpler, options.

There seems to be a ton of other rulesets created by the community, but I think most will cause the same issues.

Even if one of those rulesets ended being useful, maybe the best use of vale would be integrated with the editor to warn as you are writing, because at that moment you can simply ignore.

We can make a quick PR to remove the write-good rules.