On Monday, February 3, 2003, at 04:39 AM, Bruce Momjian wrote:
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.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?
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
---------------------------(end of broadcast)---------------------------
TIP 6: Have you searched our list archives?
http://archives.postgresql.org
