Re: [PHP-DOC] RE: [PHP-DEV] "waldschrotts guide to nifty references" - manualpagedraft, version 0.9b From: php3 <email protected>
Date: 08/20/00

Addressed to: "Phpdoc" <phpdoc <email protected>>
              php-dev <email protected>

Sorry for extending this thread, but after reading it, I find I have
some pretty strong feelings on the subject.

I definitly DO NOT want 1003 places to look for something, but I also
don't want to have to wait for pages of introductory information to
download before I can find the order of parameters for a function.

I think three 'books' would be an ideal number for PHP.

o Users Guide

You look here for information on what you can do with arrays in PHP,
how to use sessions, or upload files, etc. Topics are grouped by
activity with no concern for what functions are used to get the job
done.

I think the PHP Users Guide should assume the user knows something
about HTML, CGI, SQL and a programming language or two. First time
programmers can hit the third party tutorials for step by step
instructions.

I consider the three O'Reilly Perl books mentioned earlier to be Users
Guides. (Learning, Programming and Advanced Programming) I usually read
the Users Guide once or twice and put it away once I know enough
functions to get the job done, which is why I don't want to see this
info every time I am looking for reference data.

o Reference

This book gives concise definitions of functions, and parameters. It is
grouped by function, or purely alphabetically. Most of the time I know
what function I want to use, but need to refresh my memory on the
parameters or the return values. This is the book I grab most often.

When I write in Perl I use The Perl 5 Programmer's Reference. (Wyke,
Duncan - Ventana Communications Group - ISBN 1-56604-750-1) Over half
the book is an alphabetical list of functions, with most pages having
two functions, a handful of functions spanning two pages, only one page
with parts of three functions on it. There is a bleed to the edge of
the page that marks all the functions that start with the same first
letter, and I have written the letters on the edge of the book. That
makes for a very fast way to find details on something. Most of the
rest of the book does the same for Perl modules.

The current PHP manual is a very good reference manual. It might be
improved re-arranging parts of it, but overall it is great. I think it
would lose value if the concise function definitions are watered down
with too much info on usage.

o Extensions, Internals and Philosophy

This is the place for all the jucy tidbits that you don't have to know
to write PHP programs. Waldschrotts Guide would fit here, along with
how to write extensions, and other advanced topics that you don't have
to know to paint a web page. This might be a good place for the
developers to record why they made the choices they did, and how it
affects how scripts are run. Anything that generates 10 or more
messages on php-dev about how to do it might deserve a summary in
this manual. That wouldn't take a developer to write, but would record
the reasons and results of major development decisions.

If you just can't handle the idea of three separate 'books', this could
be mixed in with the Guide, but it is different enough I think it should
stand on its own.

Since the PHP manual is most often used via the web rather than paper
there is good reason to hyperlink extensively. It does not cost that
much to make every reference of a function in the Users Guide a link to
the function in the Reference Manual. (sounds like a program to me...)
The reference manual could include a link to the user guide chapter that
tells how to use a function and both of those 'books' could have
footnotes that mention advanced discussion in the Internals Manual.

You might even consider allowing URL's to tutorials written by others as
an acceptable annotation to the manuals. As long as it did not get
abused, what better place for links to tutorials than the bottom of the
users guide page.

I think the format of three separate books is ideal. It doesn't take
that long to figure out what is where, and once you do you can zero in
on just the information you need rapidly.

One last thing, the biggest, simple improvment to the manual you could
make for me would be to have a link in the table of contents to
"Alphabetized list of Functions". This link takes you to a page of
links, A - Z and 'All'. Each letter page lists all function names that
start with that letter. The All page lists them all on one page. The
function names are links to the function, followed by the short
description from the ref.* pages.

This way if I know the name of a function I can find it without having
to guess what category it belongs in. I do it now by typing in the URL,
but it would be nice if I did not have to take my hand off the mouse. :)

It would be even better if it listed ALL php functions, even if they
have not yet been documented

.

Rick Widmer
Internet Marketing Specialists
www.developersdesk.com