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

Dave Page wrote:

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.

We have already had several eyes look at the comment, so I am fairly
certain that there isn't anything useful. If there is, someone else
will make the same comment, and we will catch it. Ideally, we would
have no comments because it would all be in the docs.

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

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

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.

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

-----Original Message-----
From: Bruce Momjian [mailto:pgman@candle.pha.pa.us]
Sent: 03 February 2003 11:40
To: Dave Page
Cc: Neil Conway; PostgreSQL Hackers
Subject: Re: [HACKERS] 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?

OK point taken. What about the issue that the comments get merged into
later docs, which is often not helpful if someone is searching the older
docset (because they are using the older version)?

Perhaps we should then prune the garbage out of the old version, and
make the comments version specific so that we start afresh with the new
docs, but leave the useful comments against the older versions?

Regards, Dave.

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

Dave Page 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?

OK point taken. What about the issue that the comments get merged into
later docs, which is often not helpful if someone is searching the older
docset (because they are using the older version)?

Perhaps we should then prune the garbage out of the old version, and
make the comments version specific so that we start afresh with the new
docs, but leave the useful comments against the older versions?

Yes, I can see keeping the old comments on old releases, but frankly, if
it requires any special effort, it isn't worth the trouble. We are
improving this thing so fast I can barely keep up.

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

Dave Page wrote:

-----Original Message-----
From: Bruce Momjian [mailto:pgman@candle.pha.pa.us]
Sent: 03 February 2003 11:40
To: Dave Page
Cc: Neil Conway; PostgreSQL Hackers
Subject: Re: [HACKERS] 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?

OK point taken. What about the issue that the comments get merged into
later docs, which is often not helpful if someone is searching the older
docset (because they are using the older version)?

Perhaps we should then prune the garbage out of the old version, and
make the comments version specific so that we start afresh with the new
docs, but leave the useful comments against the older versions?

Regards, Dave.

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

-----Original Message-----
From: Bruce Momjian [mailto:pgman@candle.pha.pa.us]
Sent: 03 February 2003 13:04
To: Dave Page
Cc: Neil Conway; PostgreSQL Hackers
Subject: Re: [HACKERS] Interactive Documentation - how do you
want it towork?

Perhaps we should then prune the garbage out of the old

version, and

make the comments version specific so that we start afresh with the
new docs, but leave the useful comments against the older versions?

Yes, I can see keeping the old comments on old releases, but
frankly, if it requires any special effort, it isn't worth
the trouble. We are improving this thing so fast I can
barely keep up.

The only effort required would be to note and delete the 'junk' comments
which is minimal work, especially if going through them anyway. There is
no web interface for deletion (yet) but it will identify the comment IDs
for you. I'm happy to accept lists of items to delete.

Regards, Dave.

The only effort required would be to note and delete the 'junk' comments
which is minimal work, especially if going through them anyway. There is
no web interface for deletion (yet) but it will identify the comment IDs
for you. I'm happy to accept lists of items to delete.

Toss an 'Send note to moderator' ability into the comments area about a
specific comment and that may become a bit easier.

--
Rod Taylor <rbt@rbt.ca>

PGP Key: http://www.rbt.ca/rbtpub.asc

"Dave Page" <dpage@vale-housing.co.uk> writes:

Perhaps we should then prune the garbage out of the old version, and
make the comments version specific so that we start afresh with the new
docs, but leave the useful comments against the older versions?

It seems clear to me that the comments *should* be version specific,
if that's at all feasible. When we make a new release then we can
start with zero comments if that seems appropriate --- but as long as
an older set of docs remains on-line, it should have the comments that
were made for it.

regards, tom lane

-----Original Message-----
From: Tom Lane [mailto:tgl@sss.pgh.pa.us]
Sent: 03 February 2003 14:39
To: Dave Page
Cc: Bruce Momjian; Neil Conway; PostgreSQL Hackers
Subject: Re: [HACKERS] Interactive Documentation - how do you
want it towork?

"Dave Page" <dpage@vale-housing.co.uk> writes:

Perhaps we should then prune the garbage out of the old

version, and

make the comments version specific so that we start afresh with the
new docs, but leave the useful comments against the older versions?

It seems clear to me that the comments *should* be version
specific, if that's at all feasible. When we make a new
release then we can start with zero comments if that seems
appropriate --- but as long as an older set of docs remains
on-line, it should have the comments that were made for it.

Yes, from the various discussions here and elsewhere I think this is
going to be the way to go. I will make the appropriate change now.

Regards, Dave.

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

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

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: