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

Stanislav Malyshev wrote:
> HH(>> 2) as long as we do not have seperate tutorial and programmers and
> HH(>> users guide and reference but only the one and only manual it
> HH(>> should contain as much information as possible as looking through
> HH(>> the 1000 other places will almost always end up in looking at
> HH(>> 999 of them and missing the one you really needed
> So we need to start that users guide and reference guide and whatever, not
> bloat the manual.

Doesn't that just make 1003 places to have to search in, then?

> HH(>> putting as much as possible into the manual won't harm as long
> HH(>> as we manage to keep it devided in clear parts and sections
> Yes it would. It would become so huge that you won't be able to find
> anything there without a search engine.

It already has. Most manuals are already this way. The table of contents,
the index, the headers/footers in printed manuals are there for using
a *human* search engine, looking through keyword indexes, no? Can you
remember exactly where code was in what book, or would you rather have to
look through 4 or five books each time you had a question?

Indeed, if I was looking for reference information about the Zend
parsing accelerator as it related to the require and include functions,
right now, I would have to not only use one search engine, but several, to
look up information about the parsing engine, the functions themselves,
some code examples, benchmarks, etc.

> Structuring information was not
> invented just for fun. Imagine all your Perl or C or Java programming
> books now became one book called "Java manual" or "Perl manual". And then
> try to find there some tiny part.

We are talking about several different information structures. Imagine
if rather than using CPAN to get perl code, you had to search through
many different websites or sections to get sample code, tutorial docs,
usage information, and code reference, for each single function... vs
using the cookbook. Imagine, for a moment, that the monolithic "bible"
or "Special Edition Using" books (very large, and comprehensive) books
outsold the smaller books simply _because_ it reduces the searching.
(These are popular in the US, possibly elsewhere, usually 1000 or more
pages, of complete documentation, beginner to advanced.)

I do like the O'Reilly perl breakout, so a newbie can just buy the llama
(basic tutorial) before delving into the camel, which is why I suggested
a basic tutorial section in the manual, *but* if you look at well written
books for perl, they _include_ tutorials with the functions. Simple
functions have simple tutorials, complex functions have complex tutorials.

-Bop 

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