Re: Syntax issues in Policy Manual
Russ:
On Fri, Jun 26, 2009 at 10:40 PM, Russ Allbery<rra@debian.org> wrote:
> 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.
I'm happy that Debian Policy has [a] perfectionist maintainer[s]. It's
a really important document so it's worth the extra time and effort to
make sure it is totally clear and unambiguous.
>
>> 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.
Thanks. I've read the wiki and it seems relatively straightforward to
me, so I look forward to participating more on the mailing list and
other things.
>
>> 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.
Consider this added to my to-do list, though in terms of timing right
now (and my relative inexperience with tools I'd like to use like
Perl's Catalyst framework), I don't think I'll be able to produce
anything useful on the near-horizon. Sounds like a nice long-term
nicety though.
>
>> 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.)
Unfortunately I have no knowledge of how to use DocBook. I just
recently learned how to use Doxygen to document code. Consider this
added to my to-do list as well :-)
Thanks!
Jonathan
Reply to: