Re: Syntax issues in Policy Manual
Jonathan Yu <jonathan.i.yu@gmail.com> writes:
> 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)
Yes. Plus, while I'm probably a bit of a perfectionist, at least by the
standards that I prefer to apply about 80% of proposals require
attention from a Policy maintainer to write or revise wording.
Admittedly, this is often because once we touch an area, I like to clean
up any related problems in the same area at the same time, so often the
patch gets larger.
> 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.
All you've got to do is subscribe to the mailing list and read the
traffic and speak up. :) There's a lot of general information in the
Debian wiki at:
http://wiki.debian.org/Teams/Policy
http://wiki.debian.org/PolicyChangeProcess
Do let me know if you have any questions that are not discussed there.
> 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.
Yeah, that's a good point.
> 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.
Yeah, that's reasonable. I suppose it also creates an opportunity for
someone to volunteer to read the annotated version and provide patches
that roll up typo fixes, wording fixes, and so forth periodically for
review and inclusion.
Okay, given the proviso that it not be authoritative and that that be
clear, I think I can see some clear benefits to this. The constraint
that I'd put on it is that I don't think anyone who's currently working
on Policy has time to put it together or help maintain it (they can
correct me, of course, if they disagree), so we'd want a new volunteer
to do that. But if someone is interested in setting this up, I can
definitely see some benefits.
> 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.
That would be great.
(You wouldn't happen to have any DocBook expertise, would you? It would
be ideal if we could also change the format of Policy to a documentation
system that's actively maintained, since DebianDoc-SGML really isn't any
more, and doing a section-by-section wording review while changing
formats might be an interesting approach, if a longer-term project.)
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: