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

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