That was interesting. I love the TRS-80 mention. So, it seems your logic is pretty much the same as ours --- trim them up and improve the docs.
So, that particular URL was an example of what _not_ to do. I have heard folks say they like the PHP comments a lot, but I wonder how much of that is the cutesy factor of users making comments compared to good documentation that actually has useful, well structured information --- it doesn't have the cutesy factor, but it does seem more useful. :-) --------------------------------------------------------------------------- Ronald Chmara wrote: > On Monday, February 3, 2003, at 04:39 AM, Bruce Momjian wrote: > > I looked at that URL, and it is good example of what _not_ to do with > > interactive docs, IMHO. The manual page is _very_ short, and shows no > > examples. The comments have various examples/cases, with corrections > > later to earlier postings. I would think this is not what we want. We > > want a longer manual page, with _correct_ examples that show typical > > usage. > > > > I know folks like those comments, but isn't it showing cases where the > > curt documentation just doesn't cut it? > > Well, I happen to have some erm... "experience" with the PHP system. I > can offer a bit of history in this conversation about what seems to > have worked, and what doesn't work. > > What is *supposed* to happen with the pages and notes works like this: > 1. Manual page goes online. Almost all manual pages begin with a bare > skeleton, derived from the raw code itself. Some developers are nice > enough to, oh, explain what it means. :-) > 2. Comments, corrections, and additional examples are submitted. > 3. Notes and doc editors go through all the notes, roll all of the best > ones *into* the docs, delete redundancies (2 similar examples is > silly), fix errors in the page *and* other notes, and do other garbage > cleanup. > 4. Notes are removed when they are no longer relevant. A note that > duplicates current documentation would not be relevant. A note that > pertains to a version or behavior that is no longer supported is not > relevant. > 5. If a page has a lot of notes, that means it should be re-documented. > There have been days when I've cleared hundreds of "notes" with ten > lines of text, and a four line code example. > > After working with it (php's notes system) off and on for about 2 (3?) > years, here are some of the major *problems* in the PHP system: > 1. Silly slashdot mentality, were every opinion and "tip" imaginable > gets submitted into the notes. ("If running PHP on a TRS-80 tweaked out > as a hobby project, don't forget to make sure your error logs are > written to a faster device than cassette!!.") > 2. People are using the doc notes to submit bug reports. Constantly. > Annoyingly. So frequently that we automated their rejection. > 3. People are using the doc notes to submit coding questions. > Constantly. Annoyingly. So frequently that we automated their rejection. > 4. Keeping up with the submissions. PHP can get hundreds a day, of > which 98% or so are useless. There are people who read a "php-notes" > mailing list all day long, and at the bottom of each email is a set of > one-click URLs to take action... "reject", "edit", and "delete" (the > automation mentioned above). And yet, bad notes still get published, > because there's only so many a person can read... > 5. Keeping notes editors motivated. Talk about a thankless job. :-) > 6. Editing the manual page code is _much_ more complex than editing the > notes. As a result, rather than updating the manual, the notes often > get updated instead, or are never rolled into the manual. To master the > notes, you need to drive a browser. To master the docs, there's > docbook, XML, cvs, the doc structure, etc. etc. Helpful "contributors" > have an easier time with the notes. > > In regards to terse vs. verbose documentation, this comes up with PHP > every so often. There are a few different angles to the issue: > 1. Terse proponents who want the palm-pilot version or the windows > helpfile (CHM) of the PHP manual seem to want the tiniest amount of > text. Function prototypes and a description is about it, just as a > memory jogger. > 2. Slow-link, and offline browser, users are the same way, though they > may appreciate *a single* example more. > 3. The verbose proponents want user examples available in as many > formats as possible, as many tips as possible, so solving a problem > only requires *one* page. > > Well, those are the challenges I've seen. > > HTH with PostgreSQL..... > > -Bop > > -- Bruce Momjian | http://candle.pha.pa.us [EMAIL PROTECTED] | (610) 359-1001 + If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania 19073 ---------------------------(end of broadcast)--------------------------- TIP 3: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly