[PHP-DOC] Re: [PHP-DEV] "waldschrotts guide ...", a summary and a conlcusion? From: Hartmut Holzgraefe ( <email protected>) (( <email protected>))
Date: 08/21/00

André Langhorst wrote:
> Maybe it´s time for some conclusion:
>
> - the actual reference should be compact but complete
> - additonal information which could be helpful, important or
> have tutorial aspects and exceed the reference aspect
> can be added to features maybe language
>
> Maybe we should on including tutoring man-pages and extending the
> reference reference to common misunderstandings
> - phpdoc experiences
> - bugs.php.net tells us
> - other lists tell

my summary:
 
funny how far this went as it all started about the 'references'
part that is now already checked in as far as i know ...

from there on we had a little sidestep towards 'extension writing'
but this died rather quick without a real conclusion if it should
be a mannual chapter or appendix or not

  as we went on to "is the manual a manual or a reference manual
and what should it be" aka. "do we need seperate books for users
and programmers guide and manual"
  still no conclusion here as my suggestion regarding multiple
<refsect1> blocks in function pages for the creation of 'short
reference' and 'full explaination' seemed to be unheard for now
 
  even then we were perhaps talking about different things when
we mentioned 'tutorials' and in todays discussion it seemed even
worse so i'll try to sort things out a bit by defining three
different kinds of tutorial information:

1) short introductions and working examples with as little
   as possible but as much as needed information to avoid
   misunderstandings for those who do not yet know about
   all the backgrounds of a given function or extension
   (i hope my work on the imap part can serve as an example
   here although i'm not really confident or finished with it)

   i'll define this type as 'background and usage info'

2) some background information about a extensions or
   features aims, the technology, product or protocol
   behind it and a working example that uses enough
   functionality from the given extension to be somehow
   usefull

3) full featured tutorial examples within function pages

   theese i'd like to call 'tutoriallets' for now

4) full featured tutorials that go beyond the scope of php
   itselft and contain a lot of extra information about a
   given topic (like for example a tutorial about MySQL or
   mail attachments) or create a small application step
   by step
        
   lets call theese just 'tutorials'

a conclusion (?):

  the (full) manual should besides pure reference include
enough information so that (as someone who has some basic
programming experience) you can get the big picture if you
just browse through it to see whats there and can get along
the first steps with any given function or feature
  it should not replace programming introduction for beginners
or tell you everything thats possible with a given extension
but it should solve the basic problems a user may experience
  so it should contain (1) and (2) from the list above, maybe
a bit of (3), but definetly not (4), with an option to build
a pure function reference that does contain nothing of the
above

  this should satisfy the 'reference hardline' position as
represented by Stanislav as well as my 'guided reference'
position and should leave enough room for second source
tutorials of type (3) and (4) to please Zeev

  we might want to add a tutorial section to php.net, and
we might even use the XML framework we allready have to
get the flexibility of HTML and PDF output from one source
for tutorials to but i think as soon as a tutiral is complete
enough to live on its own it should not become a part of the
manual anymore 

--
Harmut Holzgraefe        hartmut <email protected>