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

Andrei Zmievski wrote:
>
> On Sun, 20 Aug 2000, Zeev Suraski wrote:
> > De-facto, the manual has always been treated as a reference manual, and not
> > a user's guide. I don't see tutorials being a part of it ever; Many
> > people have written good tutorials, and we never thought about importing
> > them into the manual, which is good. Would you expect to see tutorials in
> > UNIX man pages? Neither would I.
>
> I don't really agree with that. PHP manual is the first place people
> come to for PHP language questions. Why not provide code samples and
> tutorials as part of the manual instead of making them search through
> some other site?

especially as the second place is most likely one of the mailing lists
(and not always the right one as phpdoc subscribers know) or a question
in the annotations ... :(

it is true thatfor example the MySQL section should not teach you how
to speak SQL, thats a different story, but from my experience with the
(still unfinished) imap documentation a pure reference style
documentation
will produce far more problems than solutions as

- the extensions name is misleading as it can handle pop, nntp,
  mailbox files and, of course, imap

- it is not clear what a mailbox name is in the context of theese
  functions

- some of the functions do not make sense with some of the supported
  protocols

when i first read my way through this part of the manual it was in a
minimalistic reference form, and it was useless even if already had
a rough picture of what was going on (protocols, encodings, MIME and
such), not to speak of the missing functions, the functions documented
but not yet available in PHP4 as they had been added in PHP3 after
the code split and the errors on some of the prototypes and descriptions

to make it even worse there is no tutorial and only a well-hidden
reference text in the UW-imap c-client package itself (called
internal.txt)

so i started to add more flesh to the function descriptions and tried
to write an example for each of them, even describing some protocol
background stuff from time to time

this is not a beginners tutorial (and shouldn't be) but it has some
tutorial aspects and i think that doesn't harm at all (although i might
move some of the descriptive stuff from the functions, esp. imap_open()
to the intro part in the final version)

this is what i talk about when refering to tutorials, other
interpretations
may differ from it

if we say that the manual should not becom a 'PHP for dummies' i
totaly agree but it should contain enough background information that
someone who has done programming before and has a rough idea
what a given extension is good for and how to get started with it
without having to browse a lot of 2nd documentation sources or
fall back into try&error 

--
Hartmut Holzgraefe         
  hartmut <email protected>     http://www.six.de    +49-711-99091-77 fax:-99

-- 
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: php-dev-unsubscribe <email protected>
For additional commands, e-mail: php-dev-help <email protected>
To contact the list administrators, e-mail: php-list-admin <email protected>