Re: "waldschrotts guide to nifty references" - manualpage draft, version 0.9b

At 21:27 21-08-00, Rasmus Lerdorf wrote:

At 21:15 21-08-00, rasmus@lerdorf.on.ca wrote:

We have a bigger documentation team now than any of the other sites out there.

How would you know that? Because I have talked to most of them and am helping a couple of them.

Translations aside, I don't think the PHP documentation team is the biggest team around. Most tutorial sites have people who write tutorials on a standard basis, as well as people who write a tutorial on a specific subject. Combined, that's more than the PHP documentation team. If the PHP doc team begins writing tutorials it'll be on the expense of the manual, which would be a shame, since tutorials are already well covered by other sites.

We have the resources and the structure to do a very good job on this. The more examples we can put into the documentation, the better, and if somebody wants to write some full tutorials, I see no reason for not including them as long as they don't get in the way. That is, they would be put into the appendix or into a separate chapter so as to not interfere with the concise function reference.

I see no reason to step into something that's already covered by so many other sites. Link them. Keep the manual elite in what it is. This whole business sounds as if we're competing with other sites, when we really aren't. What does it matter whether it's it on php.net or on another site? This isn't competition. This is additional information. There is no such thing as too much documentation as long as it is well organized. And often it does matter as people look at php.net first, then ask. Cutting down on the number of questions is a good thing.

I don't see the added value of tutorials inside the manual. I'm not saying that there mustn't be any tutorials in the manual, the world won't come to a bitter end if there are; But it should be fairly clear that this is not what the manual is about. Unlike a function and a language reference, which isn't even attempted by any other site, there are plenty of (good) tutorial sites. A first step would be linking them promptly from the manual. If a member of the doc team writes a tutorial and decides he wants to publish it at no other place than www.php.net instead of on one of the tutorial sites, we can add it there, but I don't see any reason to encourage this (as in, the resources of the doc team should go mostly all towards the function/language reference). Zeev -- Zeev Suraski <zeev@zend.com> http://www.zend.com/