Re: Interactive Documentation - how do you want it towork?

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