Re: Syntax issues in Policy Manual
Russ:
On Fri, Jun 26, 2009 at 2:14 PM, Russ Allbery<rra@debian.org> wrote:
> Jonathan Yu <jonathan.i.yu@gmail.com> writes:
>
>> I agree that Policy should be kept a closely reviewed thing. But maybe
>> we can have something like AnnoCPAN, where users are allowed to
>> provide /annotations/ inline with the actual policy. So people can add
>> things like "be careful here, this means ..." or something.
>>
>> Then those annotations can be considered proposed changes for the
>> future, and the Policy folks can look through that to integrate things
>> (like clearer wording) into the actual, official Policy.
>>
>> It is, I suppose, somewhere between a full wiki and the current
>> protectionist measures :-)
>
> My concern is that, as you can see from the open bug list, we already
> have a review bandwidth problem. I'm not sure making it easier still to
> propose changes is going to help much. We need to get better at making
> changes.
That is a very good point. I imagine that there are much more things
proposed than there are people to properly review them and 'vote' on
them. (well, to the extent that seconding things counts a vote)
>
> The hard work is taking a proposal for a concrete change, thinking
> through all the implications, getting buy-in from the affected people,
> and then writing a section of Policy for it that clearly communicates
> the issue. Secondarily, we need more reviewers after people do produce
> language, although that's gotten much better than it was.
How does one go about volunteering to review the policy wording? I'm a
native English speaker so I could try my hand at making sure the
Policy remains unambiguously and helpfully worded :-) It is thankfully
in a pretty good state right now, and that couldn't have been easy.
>
> Proposing changes is the easy part. If we make that part even easier,
> we're going to end up with even more of a backlog.
The idea of something like AnnoCPAN isn't solely about proposing
changes, it is also about being able to add things like: this section
was a bit confusing, here's an example to explain what it means.
The nice thing about a separate Annotated Policy document is that
people have the choice of either reading the normal one (ie, like the
normal CPAN documentation) or reading the annotated one, which might
contain some useful help or discussion, but which is known to be
non-official. So the Debian Policy Manual remains an authoritative
document.
>
> Note that wording changes that don't change the dictates of Policy, such
> as are discussed on this thread, any Policy maintainer can just make if
> they agree. I'll be committing something from this thread shortly, for
I've noticed you've made a few changes in terms of cleaning up
wording, so thanks very much for that.
> instance, once people have had a chance to look at the new wording, and
> similar to how I just committed something for the Installed-Size
> discussion. These are fairly easy. It's the changes to what Policy
> requires that take the time and effort.
I think it's admirable that the Debian Policy maintainers have
achieved a good balance of sufficient discussion of big things, while
also avoiding the whole bikeshed argument problem. It seems that
productive work gets done with only a few back-and-forth messages with
no serious disagreements, which is great.
>
> As a Policy maintainer, I would much, much rather that wording changes
> be given in the form of a diff that I can apply than in the form of an
> annotation that I have to do more work to get into the canonical
> document. That saves me time and lets me spend more time on the hard
> problems.
If it's a particularly serious patch, but merely a little gotcha,
people are less likely to submit a diff. That's what something like an
annotated policy is all about.
For example if someone reads a section but doesn't understand it
completely on the first read, and needs to re-read it a few times,
they will probably not submit a patch. But, other people might benefit
from having an example to illustrate what is meant by that paragraph,
or something. This is somewhere where an annotated manual might help.
I don't think we'll run into any issue of developers considering that
manual *authoritative*, but it would be nice for casual developers to
drop arbitrary hints in there.
For example, the Vcs-* fields are currently not in policy, though they
are discussed in the developers' reference. That set of fields is
being discussed right now, so it doesn't yet belong in policy, but
perhaps an annotated policy could mention "the Vcs- fields are
currently a bit of an ad-hoc standard, but not yet a part of the
general Debian policy." etc.
I definitely see your point though, and I agree that we want to avoid
creating too much extra work for the Policy maintainers, especially if
there is no real perceived advantage. In that respect, I would love to
volunteer some of my time to possibly re-wording things in the Policy
to make them clearer and easier to understand for all.
Cheers,
Jonathan
Reply to: