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

On Tue, Jun 15 2021, Felipe Contreras wrote:

Ævar Arnfjörð Bjarmason wrote:

quoted

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".