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

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
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073