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

When I first saw this thread I thought of the PHP docs which I recently started
using, from a level of knowing absolutely nothing of PHP.

Sure there was some useful stuff in some of the comments but some of the pages
were very long, far more comment than manual page. A lot of the comments refer
to far earlier versions, if the reader is lucky the version addressed by a
comment is included in the comment. Also, even as a complete newbie I was able
to find errors in the comments. The upshot is that the PHP docs have a lot of
old information in them, it's guess work as to what version of PHP the comment
refers to and there are a lot of comments to read to find out this uncertain
mixture of applicable/not applicable error prone comments.[*]

On the whole, I tended stop reading the comments and looked just at the manual
page and experiment myself instead.

[*] Error prone to a large extent in the examples/techniques listed as how to
do things, the email address regexp example shown as the way that started a
whole string of followups springs to mind. However, I also found some
useful/interesting information/techniques I hadn't thought of before amongst
the stuff.

--
Nigel Andrews

On Tue, 4 Feb 2003, Bruce Momjian wrote:

>
> 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
> >