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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

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/