a detail you probably didn't know: nowhere in any #curl documentation do we use the word "very". It is a banned word enforced by a CI check. This rule encourages us to rewrite and instead use more appropriate words. Makes us write better English.
@bagder Nice! William Zinsser would approve!
Incidentally his celebrated book "On Writing Well" appears to be downloadable from archive.org and it's a must read. It changes lives.
(PDF Download link:)
https://ia800207.us.archive.org/2/items/OnWritingWell/on-writing-well.pdf
@bagder verily a good rule
@bagder Makes note to create a new protocol very://
@bagder
I was taught by DAG that "clear"/"clearly" is in this category too. Either something is clear, and the word is redundant, or it is not and it is a false claim. Extra red flags about a politician claiming something as "absolutely clear".
@bagder I will v3ry much try to circumvent that rule :D
@bagder
Word banned for just cause
@bagder Having a language model review and suggest simpler language for documentation is maybe worth exploring?
and now I'm about to drop all uses of "just"... https://github.com/curl/curl/pull/20793
@bagder
I'd kill use of 'seems', 'got' and lowercase 'get' while you're at it. Probably 'have' and 'has' too.
Do I like my documentation very precise and unambiguous? Yes! Do I manage that? Not consistently.
I would appreciate a weasel word filter for vim so that I consider my written form with the precision and specificity that it deserves.
Oh! And 'like'. 'Like' can do one.
@bagder …just when I wanted to bring that one up. 🤗
@bagder I still find myself using it frequently, but I'm training myself to rethink things when I hear myself use it. I've taken the position that using it usually means that I've made some assumptions, or oversimplified something, and I need to go back and look for them.
@bagder No, I'll keep choosing my own words, thanks.
@bagder
I say this choice is justified 😇
@bagder big fan of this move. In a similar vein, I try to avoid “obviously”.
@bagder that seems … equitable
@bagder agree when it is used to imply that something is simple, quick or trivial (when it may not be to all people).
Disagree otherwise tbh, it’s basically a synonym for “only” in most other cases, which is pretty harmless? Maybe I’m not following.
@bagder judging by the first few pages of the diff: a worthy change!
@bagder
./curl$ grep "\bjust\b" -iIr . | wc -l
569
@LangerJan yeah, it took some editing to get rid of those. It was not as easy as just deleting them all...
@bagder So... maybe....
@bagder not just, though. just is nice 😆
https://just.systems
@bagder Why's Slopilot in the replies?
@bagder That is very very interesting. But I wonder if it's very necessary?
😁
@bagder don't lie, I know your CI replaces “very” with “plus-”, which I find plusgood
@bagder I agree, but I also say to myself "very very verbose" when typing this command:
$ ssh -vvv
@bagder "just" / "simply"
@bagder very interesting 🤔
@bagder yes, I remember that meme from a few years ago. It's the kind of stuff techbros would do to feel superior. Do you also try to say "thank you" instead of "sorry"?
@bagder That sounds, good!
@bagder for a non-native speaker, what exactly is not good with the word 'very'?
@shaman007 it is too simple. There is almost always a better way to phrase the same thing without it. very happy = excited, very glad = thrilled, very hungry = starving, etc. So the use of "very" is a sign that it can be said better.
@bagder @shaman007 IMHO for technical documentation: simple is better. BTW. Some spellcheckers can help you write better style before even saving the text.
@bitnacht @shaman007 in a distributed world where everyone uses their own tools and editors we need the checks in CI anyway. Those are the rules that bind us all.
@bagder @shaman007 I just don‘t think this example will either increase your productivity nor help the people reading the paragraphs in question. But if it makes you happy: keep up the enthusiasm.
@bitnacht @shaman007 Writing coherent and good documentation is a huge task. Avoiding a single word is just a tiny little bit of that and will of course in itself not make much of a difference. But I am convinced using coherent, proper and easily read language helps users. So we try to do that.
@bagder @shaman007 so no very excited :p
@bagder @shaman007 I would add to that point by saying that in technical writing, it's usually better to use adjectives to add information, rather than just adding emphasis. For me, the only information that "very" adds to a phrase like "WizWoz is very fast" is "Wow, it sure sounds like they really want me to believe that WizWoz is fast."
I'm going to be more skeptical than if the "very" hadn't been there! If WizWoz really were fast, they wouldn't need to throw in adjectives to persuade me.
@lindsey @shaman007 indeed a good point!
@bagder thank you, mmm... a lot. No, appreciate for your answer!
@bagder o need to wrap my head around this, never thought about it before.
@shaman007 it takes a little getting used to I admit, but I find that it helps me write better
@bagder thats very interesting
my English teacher banned the use of the word "just" in most contexts
"I was just xyz..." for instance
redundant
@bagder
@bagder this reminds me of a teacher I had. Every time someone said "like" as a filler word, he yelled "LIKE!!" back at us. It was like very effective.
@bagder Truth Social ought to have a similar automated check, at least for a particular account.
@bagder That's remarkably smart :)
I can tell you that this bites me just about every time I write more than two sentences. Then I go back, edit and push a fixup commit and hope that I learned something. Again.
@bagder that's very often
@bagder I also block "just" this way, and "easy"
@derickr I'm actually currently in process of doing the same for "just"!
@bagder @derickr you might be interested in a tool like https://vale.sh (or a more minimal, but js based, https://alexjs.com).
Vale has many rulesets to improve the writing style/make all docs consistent.
@bagder Very good. 😉
@bagder *shock collar fires* You used the word "just".
that's very nice ;-)
@bagder I'm very glad you have such high standards!
@bagder curl transfers are much secure
@bagder Vary very good.
@bagder What if you wanted to document your rule against using the word?
@gruber the rule is generic: we have a list of banned words and expressions. We don't need to specifically mention the words in that list! 😀
@bagder @gruber
Full list is here in case anyone else is curious like I was:
https://github.com/curl/curl/blob/master/.github/scripts/badwords.txt#L84
