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

Stanislav Malyshev wrote:
>
> AL>> I´m really agreeing that the manual should be *most* useful and that
> AL>> seperation from reference/guide does not improve *usability*
>
> Sure it does. When you want to look up what is array_diff and go to
> ref. manual you don't want to read 5-page tutorial on how to use arrays
> and why you might want to use array_diff. You want to get it's parameters,
> short explanation and one-two examples of usage, that's it. That's the
> difference between reference manual and user's guide - the former just
> gives you a list of options, the latter really teaches you what to do with
> these options, in which cases and why.

that's why a <reference> may have a <partintro> block
before the <refentry>s

if i want to look up especially array_diff() i almost
certainly know roughly what i am looking for and go
over index (in printed matter) or quickref in online
manual

and if i do not know to much about arrays i start with
the introduction page to this section to get the big
picture

the array chapter is a bad example as it doesn't have
a <partintro>, but other parts of the function reference
have additional information on their partintro and
this tends to be more like a guide than a reference
 
it all should not go down to a beginners guide to
programming but it should contain any substantial
information and IMHO this shouldn't even stop at
the PHP<->C boundary but contain stuff like the C APIs
that are currently well hidden in the two apidoc files
as later parts

so you could read up from "getting started" to "some
insights into inner works" how to extend it myself"
or stop as soon as you have reached your personal
"level of incompetence :)"

if you do not understand what its all about in any
part or want it served in an easier form it is
always ok to have other sources of information
but thats no argument for anything being left out

PS: i always hated to have unix progammers guide
    and unix programmers reference in two different
    books where the guide always links to the
    reference but the reference part is not always
    available (in other office, not in my backpack...) 

--
Harmut Holzgraefe        hartmut <email protected>