Re: [PATCH 0/6] doc: replace "alice" and "bob" examples

[Felipe Contreras <felipe.contreras@gmail.com>]

Æ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