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

Stanislav Malyshev wrote:
> RL>> http://www.php.net/manual/features.php
> RL>> And it is most definitely a useful part of the manual. We need more of
> RL>> the same.
> Well, certainly not meaning to flame somebody's work, but of the topics
> there:
> "Error handling" is certainly reference
> "Creating and manipulating images" is a reference too (2 paragraphs
> hardly make a tutorial)
> "HTTP authentication with PHP" - reference
> "Cookies" - reference
> "Handling file uploads" - here goes something more like tutorial
> "Using remote files" - reference again
> "Connection handling" - reference
> "Persistent database connections" - reference/user's guide
>
> That's not to say these chapters are bad - on the contrary, they perfectly
> fit the manual. Maybe they need more text here and there (even a reference
> can have more than 2 paragraphs :)

And

> 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.

And

> partintro blocks I saw look like references, not tutorials. Most just
> cover what is that extension, where to take external libraries and how to
> turn it on. The don't really teach to use this extension (like user's
> guide/tutorial do).

Okay, I think I'm beginning to understand Stanislav's objections in a
clearer light. He is not against simple tutorial info in the functions,
and he doesn't want to have to dig for basic reference info. It's a
perfectly understandable issue. We all started talking about "tutorials"
with different ideas of "tutorials" in our minds, perhaps.

I consider 2-4 paragraphs and 2-4 code samples to be a tutorial, in stark contrast
to the many function pages with no explanation, or code samples, whatsoever.

I was concerned that Stanislav (et al) wanted all the pages to look like:
http://www.php.net/manual/function.session-decode.php

rather than:
http://www.php.net/manual/function.mysql-connect.php

When it seems that Stanislav is worried about 10-15 page scrolls just
to read the basic info on a function.

For larger section tutorials, (4-8 paragraphs, 15-25 lines of code), those
are already being placed into the section headers, such as
http://www.php.net/manual/ref.session.php

Perhaps a simple, labeled. link back into the beiginning (or some other way of
directing the website users to look at the section begin area, partinfo. for a
quick-start kind of guide) would also help.

-Justsummarizingpartsofthediscussionbop 

--
Brought to you from iBop the iMac, a MacOS, Win95, Win98, LinuxPPC machine,
which is currently in MacOS land.  Your bopping may vary.