Russ: On Fri, Jun 26, 2009 at 10:40 PM, Russ Allbery<[email protected]> wrote: > Jonathan Yu <[email protected]> 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 -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected]
