Re: Interactive Documentation - how do you want it towork? - Mailing list pgsql-hackers

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