[PHP-DOC] Re: [PHP-DEV] Re: "waldschrotts guide to nifty references" - manual page draft, version 0.9b From: Zeev Suraski (zeev <email protected>)
Date: 08/28/00

In order to avoid continuing this endless pointless online fight, I've
answered Stig on a personal letter.

Zeev

At 10:45 28/08/2000, Stig S. Bakken wrote:
>Zeev Suraski wrote:
> >
> > At 23:46 20/08/2000, eschmid+sic <email protected> wrote:
> > >We don't have two lines of people. We have two editors. And one of the
> > >editors believes that the manual should be as complete as in every book
> > >you can buy now.
> >
> > Uhm, the manual isn't nobody's personal toy, and the editor role in that
> > sense is technical, not 'strategic'.
>
>Wrong. It is both technical and strategic.
>
> > I really see no point in the manual competing with the books. If you try
> > to be everything, you end up doing a poor job. I'd concentrate at having a
> > good reference manual (and by design and layout, it is a reference manual,
> > rather than a book that tries to teach you what PHP is), without making
> > strict rules as to what should go in and what shouldn't. The loose
> > guideline should be that things that are beyond descriptions of what a
> > certain feature or function does should not be in the manual. People can
> > add examples in the annotations, but I don't see in-depth discussions or
> > tutorials as things that belong in that manual.
>
>What about leaving such decisions to the documentation team? Why should
>your opinion on what goes in the manual or not weigh more than that of
>the people who are actually contributing their time and efforts to make
>it happen?
>
> - Stig 

--
Zeev Suraski   <zeev <email protected>>
http://www.zend.com/