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