Re: Current Issues with perlipc.pod - should they be fixed?

Hi Yves,

On Monday 06 December 2010 10:42:23 demerphq wrote:
> On 5 December 2010 07:54, Naveed Massjouni <[email protected]> wrote:
> > This thread is really depressing.  Personally, I like all of Shlomi's
> > suggestions.  I can't fathom why bareword global filehandles are still
> > pervasive in the perl docs.  But instead of the community getting to
> > discuss the merits of the changes and then have some kind of vote, one
> > maintainer with a big ego can just say, "VETO VETO VETO ... my docs
> > are already perfect!"
> 
> I think there is a difference in modifying someone elses
> documentation, and writing a totally new doc. I also think there is a
> big difference between patches to code which fix bugs or add
> functionality, and patches to documentation that is not actually
> wrong, but instead of a style no longer in fashion. To me it is a bit
> like suggesting that Shakespeare needs to be "modernized" because of
> the archaic English he used.
> 
> However, if you, or Shlomi think you can write a better perlipc.pod
> from scratch, then you should do so, or any other doc.
> 
> If we think it is qualitatively superior then we would probably
> replace the existing version.
> 
> More likely we would end up with two docs. And the community would be
> richer for it.
> 
> So I think we are right in respecting a given documents artistic
> rights to have their vision presented as they wished, within reason.
> We can always decide not to use the doc at all if we feel they are
> being unreasonable. I doubt you would get a consensus for such an
> extreme action amongst the committers though. I think we generally
> dont feel as strongly about these changes as you seem to. Although I
> respect your reasons for doing so.
> 

Aren't you describing territoriality here?

* http://en.wikipedia.org/wiki/Territoriality_%28nonverbal_communication%29

* http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-
bazaar/ar01s11.html

(sorry for the second broken link).

I'm in no position to write my own perlipc.pod from scratch - I'd rather build 
on the efforts of tchrist and other contributors. And as Aristotle noted we 
don't need another document with the same purpose. And I'd like contributors 
to discuss changes to the documentation that they originated based on their 
merit and not "veto" them, just because they are territorial about their 
documentation. This is also because the documentation affects and reflects on 
the collective community of developers and users, and we are all held 
responsible for it.

> > What incentive would I or Shlomi or anyone else have to spend their
> > time to try to improve the docs if this is how things work.
> 
> We all have different incentives. I would hope that you dont feel that
> a predicate on your contributing is the right to change anything you
> wish however you wish. That is not how it works. No matter how much I
> wish it did sometimes.
> 
> I hope you stay positive about contributing to perl, and find other
> subjects where you can do so. We have a lot more to look into than
> Tom's docs.

The way I see it what happened was that I wrote an email with aspects of 
perlipc.pod that I found lacking, and not idiomatic up to recent best 
practices, thcrist replying that he doesn't like any of the changes and 
VETOing them (without saying why the status quo was better, just by giving 
other irrelevant reasons), and some other people discussing why they thought 
what I or other people said had a relative merit and should be implemented 
(althugh possibly, like Abigail said, not at the utmost priority). I didn't 
even start patching perlipc yet (at least not after tchrist's rewrite of its 
original version which forced me to restart my work.).

I also think that the Perl 5 documentation *should* reflect the agreed best 
practices (and I don't necessarily mean Damian's PBP). We had lexical 
filehandles since at least perl-5.6.x and everyone agrees that they are a best 
practice, and "use strict;" is also a good idea, and we encourage everybody to 
do "use warnings;" instead of "-w". Therefore, we should practice what we 
preach, and make sure that the core docs don't unnecessarily demonstrate 
paradigms that have been agreed to be bad for years.

Regards,

	Shlomi Fish

-- 
-----------------------------------------------------------------
Shlomi Fish       http://www.shlomifish.org/
My Public Domain Photos - http://www.flickr.com/photos/shlomif/

<rindolf> She's a hot chick. But she smokes.
<go|dfish> She can smoke as long as she's smokin'.

Please reply to list if it's a mailing list post - http://shlom.in/reply .