Re: "waldschrotts guide ...", a summary and a conlcusion?

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@six.de