| Message ID | cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | doc: replace "alice" and "bob" examples | expand |
On Tue, 15 Jun 2021, Ævar Arnfjörð Bjarmason wrote: > I suggested in [1] that the "alice" and "bob" examples in our > documentation would be better written without a reference to such > fictional characters, for reasons that have nothing to do with trying > to bend over backwards to avoid any reference to people's gender. It > just makes for better documentation. no, it doesn't ... and wikipedia explains it nicely: https://en.wikipedia.org/wiki/Alice_and_Bob "In cryptography, Alice and Bob are fictional characters commonly used as placeholders in discussions about cryptographic protocols or systems, and in other science and engineering literature where there are several participants in a thought experiment. The Alice and Bob characters were invented by Ron Rivest, Adi Shamir, and Leonard Adleman in their 1978 paper "A Method for Obtaining Digital Signatures and Public-key Cryptosystems".[1] Subsequently, they have become common archetypes in many scientific and engineering fields, such as quantum cryptography, game theory and physics.[2] As the use of Alice and Bob became more widespread, additional characters were added, sometimes each with a particular meaning. These characters do not have to refer to humans; they refer to generic agents which might be different computers or even different programs running on a single computer." if you want to make the docs better, have at it, but please don't do something as meaningless as replacing "bob" and "alice" because you're feeling politically correct, or woke, or whatever the hell the kids call it these days. jesus ... rday
Ævar Arnfjörð Bjarmason wrote: > I suggested in [1] that the "alice" and "bob" examples in our > documentation would be better written without a reference to such > fictional characters, for reasons that have nothing to do with trying > to bend over backwards to avoid any reference to people's gender. It > just makes for better documentation. I'm fond of Alice and Bob, and I'm saddened they are the latest casualty of the culture war, but if we are avoiding gender of examples, it makes sense to let them go. However, I want to defend this usage a little. 1. Alice and Bob are familiar, so it requires less cogntive load from the user. 2. Alice and Bob promote the usage of git as a distributed VCS, where unlike centralized VCS, you directly use the repositories of your colleagues. 3. They provide some relief to an otherwise sterile landscape. I don't think these changes make for a necessarily better documentation, just a more sterile one. Cheers.
On Tue, Jun 15 2021, Robert P. J. Day wrote: > On Tue, 15 Jun 2021, Ævar Arnfjörð Bjarmason wrote: > >> I suggested in [1] that the "alice" and "bob" examples in our >> documentation would be better written without a reference to such >> fictional characters, for reasons that have nothing to do with trying >> to bend over backwards to avoid any reference to people's gender. It >> just makes for better documentation. > > no, it doesn't ... and wikipedia explains it nicely: It doesn't make for better documentation? Maybe not, but can you comment on specific parts of the changes in this series that make it worse? > https://en.wikipedia.org/wiki/Alice_and_Bob > > "In cryptography, Alice and Bob are fictional characters commonly used > as placeholders in discussions about cryptographic protocols or > systems, and in other science and engineering literature where there > are several participants in a thought experiment. The Alice and Bob > characters were invented by Ron Rivest, Adi Shamir, and Leonard > Adleman in their 1978 paper "A Method for Obtaining Digital Signatures > and Public-key Cryptosystems".[1] Subsequently, they have become > common archetypes in many scientific and engineering fields, such as > quantum cryptography, game theory and physics.[2] As the use of Alice > and Bob became more widespread, additional characters were added, > sometimes each with a particular meaning. These characters do not have > to refer to humans; they refer to generic agents which might be > different computers or even different programs running on a single > computer." > > if you want to make the docs better, have at it, but please don't do > something as meaningless as replacing "bob" and "alice" because you're > feeling politically correct, or woke, or whatever the hell the kids > call it these days. > > jesus ... I believe that the commit message of 1/6 addresses the point you're raising here: http://lore.kernel.org/git/patch-1.6-abbb5b9ba13-20210615T161330Z-avarab@gmail.com
On Tue, Jun 15 2021, Felipe Contreras wrote: > Ævar Arnfjörð Bjarmason wrote: >> I suggested in [1] that the "alice" and "bob" examples in our >> documentation would be better written without a reference to such >> fictional characters, for reasons that have nothing to do with trying >> to bend over backwards to avoid any reference to people's gender. It >> just makes for better documentation. > > I'm fond of Alice and Bob, and I'm saddened they are the latest casualty > of the culture war, but if we are avoiding gender of examples, it makes > sense to let them go. > > However, I want to defend this usage a little. > > 1. Alice and Bob are familiar, so it requires less cogntive load from > the user. > 2. Alice and Bob promote the usage of git as a distributed VCS, where > unlike centralized VCS, you directly use the repositories of your > colleagues. > 3. They provide some relief to an otherwise sterile landscape. > > I don't think these changes make for a necessarily better documentation, > just a more sterile one. Fair enough, for what it's worth I wouldn't recommend against using these names in general, I would think you'd actively seek out those actors in e.g. cryptography documentation. But as I argue in 1/6 I think these references go over the head of most of our users, and those users are better served by more succinct documentation. The diffstat for the series as a whole increases line count, but it's because of e.g. 3/6 elaborating on the function of the --user-path switch, in the case of 1/6 we've got a reduction in lines and number of words. And as argued in 1/6 for those users who /are/ aware of "Alice and Bob" it's needless distraction. Maybe it's just me, but whenever I read references to them I keep waiting for the cryptography angle to be introduced. None of the uses in our documentation reflect that canonical usage. There's also just weird things in our documentation fixed by this series, such as referring to a random file tracked by git as "bob" instead of the more obvious "file.txt".
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > I suggested in [1] that the "alice" and "bob" examples in our > documentation would be better written without a reference to such > fictional characters, for reasons that have nothing to do with trying > to bend over backwards to avoid any reference to people's gender. It > just makes for better documentation. I actually do not mind cast of characters with concrete names, especially when there are more than three parties involved and having names for them help clarify the description. But I agree with you that Alice and Bob should be reserved for situations where appearance of Eve would reasonably be anticipated, or the use of these two names become distracting to those who happen to be aware how these characters are often used in CS literature. Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)?
On Wed, 16 Jun 2021, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > > > I suggested in [1] that the "alice" and "bob" examples in our > > documentation would be better written without a reference to such > > fictional characters, for reasons that have nothing to do with trying > > to bend over backwards to avoid any reference to people's gender. It > > just makes for better documentation. > > I actually do not mind cast of characters with concrete names, > especially when there are more than three parties involved and > having names for them help clarify the description. But I agree > with you that Alice and Bob should be reserved for situations where > appearance of Eve would reasonably be anticipated, or the use of > these two names become distracting to those who happen to be aware > how these characters are often used in CS literature. > > Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)? i look forward to the renaming of "git" to something more innocuous and palatable because, somewhere, someone could conceivably, hypothetically, theoretically take exception to it. seriously, can we start a second mailing list where people want to talk about, you know, version control? rday
On Wed, Jun 16, 2021 at 05:30:14AM -0400, Robert P. J. Day wrote: > On Wed, 16 Jun 2021, Junio C Hamano wrote: > > > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > > > > > I suggested in [1] that the "alice" and "bob" examples in our > > > documentation would be better written without a reference to such > > > fictional characters, for reasons that have nothing to do with trying > > > to bend over backwards to avoid any reference to people's gender. It > > > just makes for better documentation. > > > > I actually do not mind cast of characters with concrete names, > > especially when there are more than three parties involved and > > having names for them help clarify the description. But I agree > > with you that Alice and Bob should be reserved for situations where > > appearance of Eve would reasonably be anticipated, or the use of > > these two names become distracting to those who happen to be aware > > how these characters are often used in CS literature. > > > > Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)? > > i look forward to the renaming of "git" to something more innocuous > and palatable because, somewhere, someone could conceivably, > hypothetically, theoretically take exception to it. > > seriously, can we start a second mailing list where people want to > talk about, you know, version control? Can you please tone down your responses a bit? One of the points under discussion here is whether those names end up being confusing to users because of their use in other places (like cryptographic examples). And I think the comprehensibility of our documentation is quite relevant to the project. But even if this were done purely for reasons of gender-neutrality, I still think your response is inappropriate. You are quite welcome to argue against such a change, but snarky or dismissive responses aren't welcome. (I'm referring to the last paragraph of your other response in this thread, too. I did find the wikipedia link you sent earlier helpful to the discussion, and personally I don't find the names confusing at all, for the reasons it mentioned. But that may not be universal). -Peff
Ævar Arnfjörð Bjarmason wrote: > > On Tue, Jun 15 2021, Felipe Contreras wrote: > > > Ævar Arnfjörð Bjarmason wrote: > >> I suggested in [1] that the "alice" and "bob" examples in our > >> documentation would be better written without a reference to such > >> fictional characters, for reasons that have nothing to do with trying > >> to bend over backwards to avoid any reference to people's gender. It > >> just makes for better documentation. > > > > I'm fond of Alice and Bob, and I'm saddened they are the latest casualty > > of the culture war, but if we are avoiding gender of examples, it makes > > sense to let them go. > > > > However, I want to defend this usage a little. > > > > 1. Alice and Bob are familiar, so it requires less cogntive load from > > the user. > > 2. Alice and Bob promote the usage of git as a distributed VCS, where > > unlike centralized VCS, you directly use the repositories of your > > colleagues. > > 3. They provide some relief to an otherwise sterile landscape. > > > > I don't think these changes make for a necessarily better documentation, > > just a more sterile one. > > Fair enough, for what it's worth I wouldn't recommend against using > these names in general, I would think you'd actively seek out those > actors in e.g. cryptography documentation. I have not read cryptography documentation, so for me Alice and Bob are simply two illustrative colleagues. > And as argued in 1/6 for those users who /are/ aware of "Alice and Bob" > it's needless distraction. Maybe it's just me, but whenever I read > references to them I keep waiting for the cryptography angle to be > introduced. None of the uses in our documentation reflect that canonical > usage. It's probably not just you, but the vast majority of readers are likely not aware of any cryptographic reference. > There's also just weird things in our documentation fixed by this > series, such as referring to a random file tracked by git as "bob" > instead of the more obvious "file.txt". OK, _that_ I agree it's unequivocally an improvement. Cheers.
Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > > > I suggested in [1] that the "alice" and "bob" examples in our > > documentation would be better written without a reference to such > > fictional characters, for reasons that have nothing to do with trying > > to bend over backwards to avoid any reference to people's gender. It > > just makes for better documentation. > > I actually do not mind cast of characters with concrete names, > especially when there are more than three parties involved and > having names for them help clarify the description. But I agree > with you that Alice and Bob should be reserved for situations where > appearance of Eve would reasonably be anticipated, or the use of > these two names become distracting to those who happen to be aware > how these characters are often used in CS literature. > > Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)? I don't know anybody named Tabby or Fido (or at least any human). Maybe Mary and John, or Linda and James.
>From: Felipe Contreras <felipe.contreras@gmail.com> >Sent: June 16, 2021 4:59 PM >To: Junio C Hamano <gitster@pobox.com>; Ævar Arnfjörð Bjarmason <avarab@gmail.com> >Cc: git@vger.kernel.org; Derrick Stolee <stolee@gmail.com>; Jeff King <peff@peff.net>; Felipe Contreras <felipe.contreras@gmail.com>; >Bagas Sanjaya <bagasdotme@gmail.com>; Robert Karszniewicz <avoidr@posteo.de>; Emily Shaffer <emilyshaffer@google.com> >Subject: Re: [PATCH 0/6] doc: replace "alice" and "bob" examples > >Junio C Hamano wrote: >> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: >> >> > I suggested in [1] that the "alice" and "bob" examples in our >> > documentation would be better written without a reference to such >> > fictional characters, for reasons that have nothing to do with >> > trying to bend over backwards to avoid any reference to people's >> > gender. It just makes for better documentation. >> >> I actually do not mind cast of characters with concrete names, >> especially when there are more than three parties involved and having >> names for them help clarify the description. But I agree with you >> that Alice and Bob should be reserved for situations where appearance >> of Eve would reasonably be anticipated, or the use of these two names >> become distracting to those who happen to be aware how these >> characters are often used in CS literature. >> >> Perhaps s/Alice/Tabby/ and s/Bob/Fido/ or something like that ;-)? > >I don't know anybody named Tabby or Fido (or at least any human). > >Maybe Mary and John, or Linda and James. Stevie, Jan, Pat, Chris, Randy, and Sue (if you're a Johnny Cash fan) I have used some of those in docs.
Felipe Contreras <felipe.contreras@gmail.com> writes: > I have not read cryptography documentation, so for me Alice and Bob are > simply two illustrative colleagues. I have read cryptography documentation and seen Alice and Bob used commonly. Am I supposed to be confused if I see those names used in documentation for non cryptographic software? If Alice and Bob work there, why should they not be used here? Am I missing something? >> And as argued in 1/6 for those users who /are/ aware of "Alice and Bob" >> it's needless distraction. Maybe it's just me, but whenever I read >> references to them I keep waiting for the cryptography angle to be >> introduced. None of the uses in our documentation reflect that canonical >> usage. > > It's probably not just you, but the vast majority of readers are > likely not aware of any cryptographic reference. I find it surprising that anyone would be upset that the names Alice and Bob were being used in a non cryptographic context. >> There's also just weird things in our documentation fixed by this >> series, such as referring to a random file tracked by git as "bob" >> instead of the more obvious "file.txt". > > OK, _that_ I agree it's unequivocally an improvement. Yea, a file probably shouldn't be called bob... I would probably have gone with "foo.txt" ( but file.txt is just fine too ).
On Thu, Jun 17 2021, Phillip Susi wrote: > Felipe Contreras <felipe.contreras@gmail.com> writes: > >> I have not read cryptography documentation, so for me Alice and Bob are >> simply two illustrative colleagues. > > I have read cryptography documentation and seen Alice and Bob used > commonly. Am I supposed to be confused if I see those names used in > documentation for non cryptographic software? If Alice and Bob work > there, why should they not be used here? Am I missing something? > >>> And as argued in 1/6 for those users who /are/ aware of "Alice and Bob" >>> it's needless distraction. Maybe it's just me, but whenever I read >>> references to them I keep waiting for the cryptography angle to be >>> introduced. None of the uses in our documentation reflect that canonical >>> usage. >> >> It's probably not just you, but the vast majority of readers are >> likely not aware of any cryptographic reference. > > I find it surprising that anyone would be upset that the names Alice and > Bob were being used in a non cryptographic context. Who's upset? Not the author of this patch series, as noted in 1/6 I just think it makes for less confusing reading, since Alice & Bob in particular have implicit meanings you might guess at[1], and aside from that I think it simplifies the example the guide is getting at [2]. >>> There's also just weird things in our documentation fixed by this >>> series, such as referring to a random file tracked by git as "bob" >>> instead of the more obvious "file.txt". >> >> OK, _that_ I agree it's unequivocally an improvement. > > Yea, a file probably shouldn't be called bob... I would probably have > gone with "foo.txt" ( but file.txt is just fine too ). Git's documentation is read by all sorts of audiences, "foo" and "bar" are programmer jargon not obvious to everyone. I wouldn't say don't use it at all, but when a self-descriptive alternative such as file.txt or whatever works perfectly fine as in the case changed in this series, it's better to go with that. 1. http://lore.kernel.org/git/patch-1.6-abbb5b9ba13-20210615T161330Z-avarab@gmail.com 2. https://lore.kernel.org/git/875yyc5i6x.fsf@evledraar.gmail.com/
I suggested in [1] that the "alice" and "bob" examples in our documentation would be better written without a reference to such fictional characters, for reasons that have nothing to do with trying to bend over backwards to avoid any reference to people's gender. It just makes for better documentation. Since it's clear that Derrick's not interested in picking up that task in his parallel series[2] here a brief series to implement that. This leaves the only occurances of "alice" and "bob" (and "david" and "cindy") at the bottom of giteveryday(7). Those could also be changed, but I didn't think doing so provided a clear benefit, unlike the changes being made here. 1. https://lore.kernel.org/git/875yyp4fun.fsf@evledraar.gmail.com/ 2. pull.975.v3.git.1623766273.gitgitgadget@gmail.com Ævar Arnfjörð Bjarmason (6): gittutorial doc: replace "alice" and "bob" with "you" and "www-data" gitcvs-migration doc: replace "alice" and "bob" with "you" and "www-data" daemon doc + code comments: reword "alice" example fast-import doc: change "bob" in an example to "file.txt" doc: replace "alice" and "bob" with "jdoe" and "msmith" pack-protocol doc: use "www-data" in place of "alice" Documentation/git-credential.txt | 2 +- Documentation/git-daemon.txt | 13 ++- Documentation/git-fast-import.txt | 14 ++- Documentation/git-imap-send.txt | 4 +- Documentation/git-interpret-trailers.txt | 22 ++-- Documentation/gitcvs-migration.txt | 18 +-- Documentation/gittutorial.txt | 128 +++++++++++----------- Documentation/technical/pack-protocol.txt | 4 +- daemon.c | 10 +- 9 files changed, 112 insertions(+), 103 deletions(-)