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

Stanislav Malyshev writes: > 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. > > 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). > > -- > Stanislav Malyshev stas@zend.com > +972-3-6139665 ext.106 This is more or less what I was trying, in my clumsy fashion, to agree with. :) Although the manual does atm contains a short programmer's guide, the users should IMHO be presented with what they need to know--i.e., explanations of the way things work. This is the information they need. They don't need to know *how* they work internally; at least, they don't need to get that information from the manual. -- +----------------------------------------------------------------+ |Torben Wilson <torben@php.net> Netmill iTech| |http://www.coastnet.com/~torben http://www.netmill.fi| |Ph: 1 250 383-9735 torben@netmill.fi| +----------------------------------------------------------------+