Re: INFORMAL VOTE REQUIRED - DOCUMENTATION WORDING

[George Dunlap <george.dunlap@xxxxxxxxx>]

On Thu, Nov 30, 2023 at 10:28 PM Stefano Stabellini
<sstabellini@xxxxxxxxxx> wrote:
>
> Hi all,
>
> This vote is in the context of this thread:
> https://marc.info/?l=xen-devel&m=169213351810075

To add slightly more context.

The issue here is more than a simple "should we use the word broken or
not".  We already have a mechanism for resolving this, which is that
the maintainers of the code in question (in this case THE REST), can
vote.  In any case, on that thread, four of THE REST were opposed to
using the word "broken" in technical documentation, and one in favor.

However -- and I hope I'm not misrepresenting Andy here -- Andy thinks
that position is preposterous, and that this kind of request is a
clear example of a kind of a pattern of unreasonable review which is
damaging to the project and driving away contributors.  Daniel Smith
at least supported the use of the word "broken" in that thread as
well; and (hoping I'm not reading too much into it), the tone of
writing also suggests a level of exasperation.  Andy seems to think
there are others who agree with him as well. This specific issue has
been sort of simmering in the background since August, and we're
trying to get it resolved.

In my discussions with Andy, trying to understand his point of view,
we always reach a sort of impasse, where Andy thinks the majority of
contributors would agree with him, that insisting on removing "broken"
is a completely unreasonable request; and I think that the majority of
contributors would agree with me, that insisting on removing "broken"
is a simple enforcement of long-established norms about how technical
documentation is written.

Everyone would agree, I think, that community norms should be upheld;
everyone agrees that unreasonable nitpicking or imposition of personal
idiosyncratic preferences should be avoided; but in this case we
disagree about whether "don't use broken in technical documentation"
is a "community norm" or "personal idiosyncratic preference".

So the idea was to run a test and find out.  If most people in the
community really do think that "broken" is suitable for the
documentation in our project, then of course the maintainers should
stop objecting to that kind of language.  If most of the people in the
community think that "broken" is *not* suitable for technical
documentation, then of course this isn't an example of unreasonable
review (although other instances may be).

Fundamentally a lot of these sorts of issues come up because different
parts of the community are not "on the same page".  The question is,
how do we *get* on the same page?  I don't want to have a vote or poll
over every little issue; but if we really have a deep 2(+) / 4 split,
it's probably worth having some sort of a discussion to figure out
where we are.  Hence the poll.

I would have worded it differently; but nonetheless, it's a sort of
single data point.  What do you as the community think?  Is "this
hypercall is broken" the sort of thing you'd like us to prevent, or is
that being unreasonable?

FWIW I think a "five-point survey" would probably have been somewhat better:

Regarding the review insisting that the word "broken" be removed from
the updated documentation to the old hypercall:

( ) I think this sort of enforcement is right, and would argue that we
continue doing it
( ) I'm happy with this sort of enforcement, but I wouldn't argue for it
( ) I'm not particularly happy with this sort of enforcement, but I
wouldn't argue against it
( ) I think this sort of enforcement is unreasonable and is harming
the community
( ) I have no idea why we're talking about this, it's really not a big deal.

 -George