Re: [RFE] Demilitarize Documentation (was RE: Delivery Status Notification (Failure))

[Christian Couder <christian.couder@gmail.com>]

On Tue, Feb 19, 2019 at 12:23 PM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> Two things:
>
>  1) Whatever anyone's abstract position on the wording of our
>     documentation, either the one stored in git.git or at
>     https://github.com/git/git-scm.com there's only so much a
>     theoretical discussion like this can get us.
>
>     If you're willing to pursue this further I think it's best if that's
>     done in the form of patches to either repositories, either sent here
>     on-list (see Documentation/SubmittingPatches) or as a PR to
>     https://github.com/git/git-scm.com

I agree.

>  2) Any piece of software or technical tool is going to unavoidably need
>     to use some amount of jargon, or words that are lifted from a more
>     general vocabulary and intended to be understood in context.
>
>     Thus, when we talk about e.g. "trees" in git, it's understood that
>     we're talking about something in the context of this software
>     project, trying to go by the first Google result of "tree" isn't
>     going to get you anywhere.
>
> I for one thing those git-scm docs could be changed to eliminate those
> words for reasons entirely unrelated to them somehow being religious or
> militaristic.

I agree that it would be a much better outcome of this discussion.

>  * The docs already use "integration manager" and then introduce
>    "dictator" as a synonym in the context of explaining the workflow of
>    the kernel.
>
>    They could instead use "main integrator" or something, since the
>    point of the example is to explain how git can be used to manage
>    distributed repositories that are integrated in a hierarchical
>    manner.

I would suggest considering "maintainer" or "main maintainer" or "top
level maintainer", as I think "maintainer" is one of the most common
word used for the role in the Linux kernel and Git communities. By the
way it's often used in expressions like "sub-system maintainer", which
maybe could be used to replace "lieutenant".

(In Git Rev News I think I have always used "the Git maintainer" to
talk about Junio for example.)

>    Making assumptions about how much power the "main integrator" has to
>    approve/reject changes is irrelevant to that explanation.
>
>    E.g. the kernel could also decide to make the "main integrator" some
>    purely automated process that always approves changes from
>    lieutenants and the hierarchical example would be just as true.

Thanks for your insight on this,
Christian.