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

Good post Ron!

> Well, there are a few flavours of the manual, on-line, right now,
depending
> on *how* you look at it and on what page you're on:
>
> 1. Raw reference.. [chop]
> 2. Illustrative reference...[chop]
> 3. Ilustrative, annotated, reference with full code examples...[chop]

Perhaps another way to look at this is as a process of growth.

Ideally, every manual entry should be like #3 - however, I don't think that
this is currently possible.

What if we decided that #1 was required - if a function or feature is
available then this must be in the manual.
#2 is a should
#3 is the end goal

> Basically, we already have these different "schools of thought" in the
manual,
> but there is not a cohesive approach yet....
>
> Depending on a section's popularity and usage (as well as the quality and
> quantity of official documentation), the annotations range between 0 and
> 50... the most frequently used, but poorly documented, pages seem to
> have the most annotations (regexps, sessions, etc.). Pages with more
> examples and more explanations seem to suffer from much fewer "how do
I..."
> questions, and I assume that is a result of the documentation meeting the
> needs of most users.
>
> I have not seen a *single* annotation yet which complains about having too
> much documentation, or too many answers. Just too many unanswered
questions.
>
> > RL>> doesn't say "Reference Manual" anywhere. It says "PHP Manual". It
> > RL>> includes a section called "Language Reference" and it includes
another
> > RL>> section called "Function Reference", but there is a reason that
these are
> > RL>> individual sections. If somebody wants to write some good
tutorials
> > RL>> explaining various concepts in PHP, then they will be added. Have
a look
> > RL>> through the things in the "Features" section of the manual.
> > I don't think tutorials really should be there.
>
> Whether or not they are "officially" put in there, they're becoming part
of the
> annotations, because the _users_ of the online manual value them. There
are
> tutorials in the form of simple explanations, simple to complex coding
> variations... everything from variable assignment to complex db-based
> session management has been added to different pages, usually as the
beginning
> of each section, or on the page of the most frequently used function.

Perhaps the manual notes should be changed to a knowledge base format.
End users would only have to view the questions when searching / reviewing
the base, instead of having to dig through unformatted notes.

> We could also add a simple "Tutorial" section to the manual, as one
section,
> or a tutorial for each section sub/section, to explain the usage of the
functions
> in the section. That would be much more orderly than a tutorial for each
> *function* in the existing subsections (postgreSQL, XML, etc.). For larger
> sections or function groups, we would need more tutorials, of course, but
> for something like basic MySQL usage, it's a fairly simple 20-30 lines of
> code with comments.

I still think that we should link to any large resources, instead of
including them in the main document.

> It doesn't have to be, but it could. The concept of "book" may or may
> not hold well here.... I doubt that most people are printing the pages
> out.

(Just to be contrary) I have three copies that float around my work place.
;)

[chop]
> You see, if people wanted to just download/buy a reduced book or manual
> for PHP, they could just grab sections that they desired, if we set up
> sectional downloads (not a bad idea, considering how many sites probably
> only use 30-40% of the manual, i.e. many siyes on MySQL don't want or
> need Oracle, Postgres, DB2, etc.). It also fits in with the workflow to
> only compile and update sections as _needed_ for changes.

This idea I really like - if the documentation is split up, then it should
be easier to build and manipulate.
Each major group of functions would be a separate document. Each tutorial
would be a separate document.
A single framework document could tie the pieces together on the site.

 - zak