Æ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. -- Felipe Contreras
