Re: "waldschrotts guide to nifty references" - manualpagedraft, version 0.9b

Stanislav Malyshev wrote: > RL>> What makes you think the online manual is only a reference manual? It > Because it is like any of dozens of reference manuals I saw. If it goes > like duck and quacks like duck, you know... At least now, it's clearly a > reference manual. I don't know what was the intent, maybe it was the > user's guide, but what came out is clearly like reference manual :) 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. No examples, no color commentary, no help for anybody other than the individual trying to look up whether a function returns 0 or 1 upon success. Not even very complete in that sense, are many functions are missing even that much, and simply state parameters. This is fairly pointless, as it's in the source code anyways, and by the time a developer reaches a level where this is their *only* need for the manual, they're probably reading the source. 2. Illustrative reference. Basic code examples of primitives, cross-referenced examples, semi-verbose explanations of usage. Good for users who have a basic understanding and wish to explore new functions, but are adept enough with PHP that they do not need full examples. 3. Ilustrative, annotated, reference with full code examples. These pages are filled with a few documented code examples, function information and history, mini-tutorials, code hacks, workarounds, cross referenced, and hyperlinked to other web pages. Good for a wide range of users, as *ignoring* unnneded information is much easier than not being able to find the needed information at all. 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 > RL>> 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. > Manual takes 5-10 minutes to compile even now, Okay, I don't see the issue here. For the compiled manual to fall behind the XML documentaion, if were were updating every 24 hours, we have a total of 1440 minutes between refreshes. That's up to 144 times the current manual size. Everything else is just maintaining on on-line copy while the off-line compile builds, and a quick rsync task to push out the current files. > and adding tutorials here will make it unmaintainable. Why? If we add more information to PHP docs, it becomes unmaintainable? Are we at a threshold where we cannot add more *functions*, as it would make the manual too big? > Why just not to make another book and call it PHP Tutorials or whatever? 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. > Why it must be one book that does all? 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. > I just > imagined that all my Perl books suddently became one, and believe me, this > is a frightening thought... We better don't do that. Well... I've been in touch with one of the people for largish documentation publishing house, who is part of an online project, to put all of their 50+ authoritative computer books into internet form (guess who.). Rather than splitting up their documentation among many websites, they are putting it on one site, and offering it all as one entity, where you can access the sub-portions as needed (selling sections of the library, on one site)... Which brings to mind a compromise, as well as something that might help in the workflow. We could make the printed documentation more like the website, partitioned into "use areas". Rather than only offer annotated and non-annotated, we could offer manual "areas". 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. Thoughts? One of your humble annotation trolls, -Bop -- Brought to you from iBop the iMac, a MacOS, Win95, Win98, LinuxPPC machine, which is currently in MacOS land. Your bopping may vary.