Hi Bruce,

Have you ever used the idocs on the PHP site? I find them invaluable,
though there are many useful comments that you might not want to
incorporate into the official docs for fear of bloating them. Take a
look at http://www.php.net/manual/en/function.intval.php for example.

Regards, Dave.


> -----Original Message-----
> From: Bruce Momjian [mailto:pgman@candle.pha.pa.us] 
> Sent: 03 February 2003 01:09
> To: Dave Page
> Cc: Neil Conway; PostgreSQL Hackers
> Subject: Re: [HACKERS] Interactive Documentation - how do you 
> want it towork?
> 
> 
> 
> I don't think I was clear before.  When someone is looking at 
> the interactive docs, I would like them to say, "Oh, there's 
> a comment.  I better read that in case it will help me."  If 
> we have old comments, their "special" value becomes 
> diminished.  That's why I think they should be removed as 
> they are reviewed.
> 
> --------------------------------------------------------------
> -------------
> 
> Dave Page wrote:
> > 
> > 
> > > -----Original Message-----
> > > From: Neil Conway [mailto:neilc@samurai.com]
> > > Sent: 02 February 2003 20:52
> > > To: Dave Page
> > > Cc: PostgreSQL Hackers
> > > Subject: Re: [HACKERS] Interactive Documentation - how do you 
> > > want it towork?
> > >
> > > > 2) Bearing in mind your answer to the previous question, should 
> > > > all
> > > > the comments be deleted when useful examples have been 
> > > merged into the
> > > > main documents (remember that the definition of 'useful'
> > > may vary), or
> > > > should we only remove the 'junk' ones?
> > > 
> > > Once the comment's suggestion has been incorporated and the
> > > docs updated, I think it should be removed. Just like in the 
> > > rest of the documentation, there's no point presenting 
> > > duplicate content to the user, so we should only keep the 
> > > idocs comments that are still relevant. The same goes for 
> > > comments that have no value (e.g. support requests).
> > 
> > My concern here is that what (for example) Bruce decides is not a 
> > useful addition to the docs themselves, maybe something that would 
> > have helped me with some bizarre problem. If we dump *all* the docs 
> > after they have been merged then I might lose that helpful tip.
> > 
> > Also, and perhaps more importantly, the comments will be 
> merged into a
> > *future* version. If I am running 7.2, I'm going to look at the 7.2 
> > docs, not 7.3.
> > 
> > Regards, Dave.
> > 
> > ---------------------------(end of 
> > broadcast)---------------------------
> > TIP 2: you can get off all lists at once with the unregister command
> >     (send "unregister YourEmailAddressHere" to 
> majordomo@postgresql.org)
> > 
> 
> -- 
>   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, 
> Pennsylvania 19073
> 

Mon, 3 Feb 2003 08:47:14 -0000
"Dave Page" <dpage@vale-housing.co.uk>
Re: Interactive Documentation - how do you want it towork?

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?

---------------------------------------------------------------------------

Dave Page wrote:
> Hi Bruce,
> 
> Have you ever used the idocs on the PHP site? I find them invaluable,
> though there are many useful comments that you might not want to
> incorporate into the official docs for fear of bloating them. Take a
> look at http://www.php.net/manual/en/function.intval.php for example.
> 
> Regards, Dave.
> 
> 
> > -----Original Message-----
> > From: Bruce Momjian [mailto:pgman@candle.pha.pa.us] 
> > Sent: 03 February 2003 01:09
> > To: Dave Page
> > Cc: Neil Conway; PostgreSQL Hackers
> > Subject: Re: [HACKERS] Interactive Documentation - how do you 
> > want it towork?
> > 
> > 
> > 
> > I don't think I was clear before.  When someone is looking at 
> > the interactive docs, I would like them to say, "Oh, there's 
> > a comment.  I better read that in case it will help me."  If 
> > we have old comments, their "special" value becomes 
> > diminished.  That's why I think they should be removed as 
> > they are reviewed.
> > 
> > --------------------------------------------------------------
> > -------------
> > 
> > Dave Page wrote:
> > > 
> > > 
> > > > -----Original Message-----
> > > > From: Neil Conway [mailto:neilc@samurai.com]
> > > > Sent: 02 February 2003 20:52
> > > > To: Dave Page
> > > > Cc: PostgreSQL Hackers
> > > > Subject: Re: [HACKERS] Interactive Documentation - how do you 
> > > > want it towork?
> > > >
> > > > > 2) Bearing in mind your answer to the previous question, should 
> > > > > all
> > > > > the comments be deleted when useful examples have been 
> > > > merged into the
> > > > > main documents (remember that the definition of 'useful'
> > > > may vary), or
> > > > > should we only remove the 'junk' ones?
> > > > 
> > > > Once the comment's suggestion has been incorporated and the
> > > > docs updated, I think it should be removed. Just like in the 
> > > > rest of the documentation, there's no point presenting 
> > > > duplicate content to the user, so we should only keep the 
> > > > idocs comments that are still relevant. The same goes for 
> > > > comments that have no value (e.g. support requests).
> > > 
> > > My concern here is that what (for example) Bruce decides is not a 
> > > useful addition to the docs themselves, maybe something that would 
> > > have helped me with some bizarre problem. If we dump *all* the docs 
> > > after they have been merged then I might lose that helpful tip.
> > > 
> > > Also, and perhaps more importantly, the comments will be 
> > merged into a
> > > *future* version. If I am running 7.2, I'm going to look at the 7.2 
> > > docs, not 7.3.
> > > 
> > > Regards, Dave.
> > > 
> > > ---------------------------(end of 
> > > broadcast)---------------------------
> > > TIP 2: you can get off all lists at once with the unregister command
> > >     (send "unregister YourEmailAddressHere" to 
> > majordomo@postgresql.org)
> > > 
> > 
> > -- 
> >   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, 
> > Pennsylvania 19073
> > 
> 

-- 
  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, Pennsylvania 19073

Mon, 3 Feb 2003 06:39:46 -0500 (EST)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: Interactive Documentation - how do you want it towork?
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?

Bruce is spot on here.  Manuals pages that don't need an extensive
amount of comments are likely the best way to go, and they're even
distributed with the source code of PostgreSQL, unlike the comments.

:-)

Regards and best wishes,

Justin Clift

-- 
"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
- Indira Gandhi



Mon, 03 Feb 2003 22:33:04 +1030
Justin Clift <justin@postgresql.org>
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


Mon, 03 Feb 2003 22:00:24 -0700
Ronald Chmara <ron@Opus1.COM>
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@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Tue, 4 Feb 2003 06:42:26 -0500 (EST)
Bruce Momjian <pgman@candle.pha.pa.us>
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
> > 


Tue, 4 Feb 2003 12:10:08 +0000 (GMT)
"Nigel J. Andrews" <nandrews@investsystems.co.uk>
Re: Interactive Documentation - how do you want it towork?