[PHP-DOC] Re: [PHP-DEV] "waldschrotts guide to nifty references" - manualpage draft, version 0.9b From: Hartmut Holzgraefe ( <email protected>) (( <email protected>))
Date: 08/19/00

Stanislav Malyshev wrote:
>
> SM>>> What for? Refcounting is not visible from userspace in no way,
> SM>>> why do you need it in the manual?
>
> AL>> It´s an interesting fact for switchers and experts,
> AL>> I don´t think it´s a good idea to hide all technical details,
> AL>> we´re open source so why we´re closed technology
>
> It's not closed. But not everything belongs to the manual. We should not
> bloat it with unnecessary details. Manual should serve it's purpose,
> not try to be jack-of-all-trades.
>
> SM>>> Calling existing PHP manual "few" is a huge underestimate, IMO.
> SM>>> But let's not bring there everything and the kitchen sink. Manual
> SM>>> should be just reference, not all-about-the-subject tutorial.
>
> AL>> You just said. It´s reference ;)
> AL>> reference for technical details IMHO, a manual should contain as much
> AL>> useful information as possible
>
> No. We could put there description of Zend API, details of Zend memory
> manager, API of zend hashes and 1001 things - but they *do not belong
> there*. It's a PHP manual, and this has nothing to do with PHP as a
> language. There are 1000 other places (books, Zend.com, php.net,
> phpwizard.com) where PHP articles and details are due. Manual is not only
> place to put PHP/Zend material, and it should be kept clean. Not as much
> information as possible, but exaclty as much information as needed for a
> reference guide (as opposed to a tutorial, programmer's guide and user's
> guide).

(crossposted to phpdoc as it might be of interest for the documenters/
translators too)

just two points from my own experience:

1) finding information about internals, esp. extension interface to
   both php core and Zend is not easy (yet), even if you have access
   to all the books around and i would welcome a manual part dedicated
   to this special topic

2) as long as we do not have seperate tutorial and programmers and
   users guide and reference but only the one and only manual it
   should contain as much information as possible as looking through
   the 1000 other places will almost always end up in looking at
   999 of them and missing the one you really needed

   putting as much as possible into the manual won't harm as long
   as we manage to keep it devided in clear parts and sections
   ok, it would lead into having even more pages, but with the
   ~1000 pages we have right now (print version) i don't think
   theres anybody out there printing it in total anyway, whoever
   wants to have printed material will select the parts he really
   needs
   and it would lead in longer xml translation times as the current
   build system is not able to do incremental builds but that is
   another story 

--
Harmut Holzgraefe        hartmut <email protected>