nick at ccl4
May 10, 2008, 7:14 AM
Post #12 of 13
(649 views)
Permalink
|
|
Re: [PATCH] Add Some Links to External (WWW) Resources to the Perldocs
[In reply to]
|
|
On Sat, May 10, 2008 at 01:48:42PM +0300, Shlomi Fish wrote:
> Hi all!
>
> On Thursday 08 May 2008, David Landgren wrote:
> > Shlomi Fish wrote:
> > > This patch which aims to set a more general direction for consideration
> > > aims to add some hyperlinks to external resources to the perldocs of the
> > > core Perl documentation. It is naturally still a very preliminary effort.
> >
> > Getting around to this (I'm summarising, and late as usual), I think the
> > best thing is to not include such information in the documentation,
> > licensing issues aside.
> >
> > All this really does is add information highly susceptible to bitrot,
> > thus adding to the burden of maintenance.
>
> I don't think we should fear increasing the burden of maintenance. Arguably a
Like David, I fear it. It will kill us if we don't constrain it.
Now, what is worthwhile to add despite it increasing mainentence, versus what
is not worth it, because the addition is less than the cost, that's an
independent discussion.
> quality product requires a lot of maintenance work, and the higher quality,
> then generally we should expect the maintenace work to increase. We can
> reduce the amount of maintenace work in many ways, but it's a poor excuse for
> not doing the right thing.
Unless, of couse, on the basis of idealism we take on so much that *should*
be done, that we never get any of it done. We are all only human, after all.
> > If you have time to devote to Perl documentation, and we all know how
> > much it needs it, the issue is very much the Expérian "what can be
> > removed?" rather than "what can be added?"
>
> Just a note: I think it's dangerous to mercilessly apply the
> standard "Perfection is achieved not when there is nothing more to add but
> nothing left to take away", to everything you encounter. Otherwise, you're
> encouraging making such famous quotes as dogma.[1]
It's not clear to me that David was saying that.
> I think it doesn't always hold for human text and communications. Often short
> texts (especially short sentences, quotes or aphorisms) can be misunderstood
> and misapplied and you need to expand on them a bit and explain them. It
> happened to me with my essays many times, and I'm not aiming for brevity too
> much.
>
> I think that if we're not going to explain how UNIX-like multi-processing
> works, then a link that explains the otherwise opaque text would be a good
> idea, so people can click it and be enlightened.
There is a fundamental conflict in the Perl documentation as is.
People are tugging it in both ways - it's trying both to be a reference
manual (terse, to the point), and an introduction/tutorial.
It can't be both. It certainly can't be all things to all people.
I'm with David - the road you're suggesting would end up with us adding all
of the concepts in W. Richard Stevens' books (or at least a link out) because
someone might have come to Perl without a background in that particular thing.
We have to assume some level of intelligence on the part of the readership.
If they don't know a concept, they will be smart enough to research it for
themselves.
Nicholas Clark
|
external-links-patch-1.diff
