Raku
Simple deletion of "of course" phrases.
'Of course' can be vaguely insulting. Taking its meaning to the extreme gets something like 'This is so obvious it should not need stating'.
Readers should be more generous than that. But if the of-courseness of the statement is clear to the reader, or not; the 'of course' is just noise.
So here are a bunch of simple deletions of the phrase.
I have a few more that involve a little more sentence restructuring; should those follow on this branch or not?
I think the few changes I've looked at seem reasonable. I disagree that they are condescending (but I tend to use the phrase myself).
I am sorry but I don't think this is the way to proceed in this case. The main problem is you're not addressing an issue, so we could follow the "If it's not broken, don't fix it". But even if we agreed that "of course" is a problem, we might or might not agree on how to tackle it. In most cases I would try to change the "of course" to references to a glossary or to a concept, or possibly rephrase it; in some cases, if it's "of course", the sentence can possibly be removed entirely. Finally, if it's a matter of style and we don't want it to happen again we should include a test after reaching a consensus. In general, any change that affects so many files needs to be considered carefully.
In my opinion, with an "of course" it's irrelevant whether it is condescending or not. As the suggested changes have proven (to me at least), is that the "of courses"'s are not needed.
Reading an "of course" by a person who doesn't see that it follows from whatever is being said, enforces that they didn't get it in an unfriendly way. I would therefore suggest that if we deem an "of course" necessary in a text, it should be in the form "from this then follows" or so. This is more neutral, and should be equally understandable for the people who already followed it, or the people who would need to re-read the previous to understand that "it follows" from the previous.
FWIW, I did not see any such cases in this PR.
In my opinion, with an "of course" it's irrelevant whether it is condescending or not. As the suggested changes have proven (to me at least), is that the "of courses"'s are not needed.
Reading an "of course" by a person who doesn't see that it follows from whatever is being said, enforces that they didn't get it in an unfriendly way. I would therefore suggest that if we deem an "of course" necessary in a text, it should be in the form "from this then follows" or so. This is more neutral, and should be equally understandable for the people who already followed it, or the people who would need to re-read the previous to understand that "it follows" from the previous.
FWIW, I did not see any such cases in this PR.
I see merit in that argument, and may or may not agree with it. Still, a PR is not the proper place to get to a consensus on whether something constitutes a problem or not. It might be a problem, it might be part of a wider-ranging problem (has anyone looked at the use of "obviously"?), or it might not; it might be, and in that case we will not want it to show again in the future via testing. But PRs are intended to propose solutions to something that's widely agreed to be a problem. So I encourage you to open an issue, and let's try and find an agreement there.
Hi, thanks for your attention to docs!
I took just one example from the original document:
Of course, you can read from files using the
L<IO::Handle|/type/IO::Handle>type, which gives you a lot finer control over what you're doing:
Can you please elaborate what exactly is insulting in this sentence?
You noted "taking its meaning to the extreme" makes it so, but is it necessary and welcome to do so? I am pretty sure I can rewrite almost any sentence so that it reads like an insult, but why should I?
...
While I agree there are various guidelines on how to write educational texts, keeping the text a bit "water-y", not turning it into a very dry reference-like text is important to make reading easier.
Just as before, we have 500+ tickets to resolve with a lot of content missing and the underlying infra not being automated enough, with flawed search etc, and while even small tweaks help to improve the situation, this one feels like the time can be more efficiently spent elsewhere.
I take "of course" as a small apology by the writer that they do not know whether or not the reader needs to be reminded of what follows. English has many connectives that help the flow of thought from one topic to another, and sometimes "of course" is the best one. Of course, I could be wrong... :-)
Larry
On Mon, Dec 6, 2021 at 6:10 AM Altai-man @.***> wrote:
Hi, thanks for your attention to docs!
I took just one example from the original document:
Of course, you can read from files using the LIO::Handle|/type/IO::Handle type, which gives you a lot finer control over what you're doing:
Can you please elaborate what exactly is insulting in this sentence?
You noted "taking its meaning to the extreme" makes it so, but is it necessary and welcome to do so? I am pretty sure I can rewrite almost any sentence so that it reads like an insult, but why should I?
Like this:
Readers should be more generous than that
Taking it to the extreme, you "assume the readers are incompetent, fragile people who will feel themselves highly distressed because of a couple of common words, thus belittling their ability to cope with words not even intending to insult them in any manner".
...
While I agree there are various guidelines on how to write educational texts, keeping the text a bit "water-y", not turning it into a very dry reference-like text is important to make reading easier.
Just as before, we have 500+ tickets to resolve with a lot of content missing and the underlying infra not being automated enough, with flawed search etc, and while even small tweaks help to improve the situation, this one feels like the time can be more efficiently spent elsewhere.
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/Raku/doc/pull/3993#issuecomment-986810940, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABHSYWZWJIPIQI73ARGIVTUPS753ANCNFSM5JLZXSXQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.
My PR has problems. If I read the room well, those are 1) procedural error, 2) it is a precursor to much more of the same, 3) my poor justification, and 4) creating an alienating dryness.
For not following procedure, I don't feel much guilt. None of my four PRs have followed an issue. I think this rule was invoked due to the second problem of expanding to a larger policy matter. That is reasonable in the expectation and the response.
As to making a lousy case, this one is to improve the situation. That comment was kindly read. Thank you all.
Dryness is a concern I will address later. Here, I will point out it is the only criticism of the changes per se.
As to the size of the can of worms. I recall submitting 28 deletions. I am holding two that have the same problem but also needed some small edit. There are only nine other usages of 'of course'; three should be fixed.
In some sense, we are here now. I suggest resolving the PR as efficient use of our efforts. Else, I can move the following to an issue. If neither is wanted; I may take my marbles home in a snit, but you may be sure I'll soon return to play and to find my marble bag.
My full attestation:
This is all focused on 'core reference text' which is where concepts are usually named not explained.
@Altai-man, Even the modern, informal reference texts are mostly in the dry style at the core. In the more explanatory text and around the edges you find quirkiness, humor, anecdotes and other decorations. "Of course" is none of those.
@TimToady, your comment supports the changes in two ways. First, by substituting an idiosyncratic meaning, you demonstrate how useless the phrase's normal meaning is. "FWIW" and "Know this brave neophyte" also work as well for me. Second, you make it about remembering. Who reads to remember easily skips over non-pertinent words. Such skipping is a tiny waste of energy. So it is a tiny argument for removal. Additionally, 'of course' does have meaning, not the ones sumbitted above. As used, it means obviously or from the aforesaid, it is obvious that. Only those reading to learn will worry over the phrase when the meaning conflicts with their understanding; because the author is telling them their understanding is insufficient. This is not something to do unintentionally. Not because it is insulting, but because it is not helpful or worse. Distracting is worse, the reader looks more deeply at the most authoritative reference for the not-there answer to a not-meant question. This sounds unimportant until you add in a beginner's likely misunderstandings of concept or syntax.
If A and B are just facts you are conveying to the reader, there is no inherent need to state that either is obvious.
Any unnecessary meaning is a potential distraction.
Neutral substitutes are '', 'Also', and 'And'.
30
I'm fine with these changes as is, and suggest maybe we should add a note about this to the style guide as well (which based on discussion here should also be a PR that can be approved or not)
Sorry, what is the current state of this PR? Honestly, I am completely indifferent towards "of courses" but open issues and PR's irk me. It's like having dirt on the floor.
Also, even if I personally think time and energy could indeed be better spent elsewhere, the author did put time and energy into doing something that can at least be argued for. Fortunately, the lack of resolution didn't keep them from continuing but I think unresolved issues/PR's without clear and straightforward feedback are discouraging in general.
Re-reading my 1 year old reaction, this PR looks to me like we shouldn't have argued about it in the first place.
All the replies (except my one) are in general positive or neutral towards the changes, except for the wording being different.
As for the downvotes, I can assume the reaction is either "it's such a tiny edit, don't spend time on that" or "I'm used to this style, don't change it". The latter one is a terrible argument. Otherwise, please feel free to argue with me on this one.