Thread: Interactive docs idea

Interactive docs idea

From
Christopher Kings-Lynne
Date:
Hi guys,

After working on PHP for a few weeks, I see that what they do with their 
interactive docs is have any comments posted get emailed to the docs 
list.  Do we do this?

That was, good comments are immediately integrated into the manual.

Chris


Re: Interactive docs idea

From
Alvaro Herrera
Date:
On Thu, Apr 14, 2005 at 09:41:43AM +0800, Christopher Kings-Lynne wrote:

> After working on PHP for a few weeks, I see that what they do with their 
> interactive docs is have any comments posted get emailed to the docs 
> list.  Do we do this?

I think it's an interesting idea to mail the comments to pgsql-docs, but
*please don't* start emulating the PHP behavior regarding comments
(leaving the "relevant" ones forever) :-(  I think the PHP manuals are
very low quality because of the information in comments which really
belongs in the main text body (which is crappy in PHP's manual anyway
IMHO.)

Also we could take care of comments asking for support if we do this.
Not sure if there are a lot of those, but I remember seeing some
in the past.

-- 
Alvaro Herrera (<alvherre[@]dcc.uchile.cl>)
"Es filósofo el que disfruta con los enigmas" (G. Coli)


Re: Interactive docs idea

From
Greg Stark
Date:
Alvaro Herrera <alvherre@dcc.uchile.cl> writes:

> I think it's an interesting idea to mail the comments to pgsql-docs, but
> *please don't* start emulating the PHP behavior regarding comments
> (leaving the "relevant" ones forever) :-(  I think the PHP manuals are
> very low quality because of the information in comments which really
> belongs in the main text body (which is crappy in PHP's manual anyway
> IMHO.)

It seems that's not much of a danger -- the interactive Postgres documentation
hardly gets any comments at all in the first place. It would be a big
improvement if there were some way to encourage many more comments.

-- 
greg



Re: Interactive docs idea

From
Christopher Kings-Lynne
Date:
> It seems that's not much of a danger -- the interactive Postgres documentation
> hardly gets any comments at all in the first place. It would be a big
> improvement if there were some way to encourage many more comments.

Only link to the version with comments.

Chris



Re: Interactive docs idea

From
"Dave Page"
Date:

> -----Original Message-----
> From: pgsql-hackers-owner@postgresql.org
> [mailto:pgsql-hackers-owner@postgresql.org] On Behalf Of Greg Stark
> Sent: 14 April 2005 04:54
> To: pgsql-hackers@postgresql.org
> Subject: Re: [HACKERS] Interactive docs idea
>
> Alvaro Herrera <alvherre@dcc.uchile.cl> writes:
>
> > I think it's an interesting idea to mail the comments to
> pgsql-docs, but
> > *please don't* start emulating the PHP behavior regarding comments
> > (leaving the "relevant" ones forever) :-(  I think the PHP
> manuals are
> > very low quality because of the information in comments which really
> > belongs in the main text body (which is crappy in PHP's
> manual anyway
> > IMHO.)
>
> It seems that's not much of a danger -- the interactive
> Postgres documentation
> hardly gets any comments at all in the first place. It would be a big
> improvement if there were some way to encourage many more comments.

We can get from 2 - 10 a day I would guess. They get mailed to a closed
list for moderation.

Regards, Dave


Re: Interactive docs idea

From
Andrew Dunstan
Date:

Christopher Kings-Lynne wrote:

>> It seems that's not much of a danger -- the interactive Postgres 
>> documentation
>> hardly gets any comments at all in the first place. It would be a big
>> improvement if there were some way to encourage many more comments.
>
>
> Only link to the version with comments.
>
>

No thankyou. I prefer mine straight.

cheers

andrew


Re: Interactive docs idea

From
Robert Treat
Date:
On Thu, 2005-04-14 at 03:56, Dave Page wrote:
>  
> 
> > -----Original Message-----
> > From: pgsql-hackers-owner@postgresql.org 
> > [mailto:pgsql-hackers-owner@postgresql.org] On Behalf Of Greg Stark
> > Sent: 14 April 2005 04:54
> > To: pgsql-hackers@postgresql.org
> > Subject: Re: [HACKERS] Interactive docs idea
> > 
> > Alvaro Herrera <alvherre@dcc.uchile.cl> writes:
> > 
> > > I think it's an interesting idea to mail the comments to 
> > pgsql-docs, but
> > > *please don't* start emulating the PHP behavior regarding comments
> > > (leaving the "relevant" ones forever) :-(  I think the PHP 
> > manuals are
> > > very low quality because of the information in comments which really
> > > belongs in the main text body (which is crappy in PHP's 
> > manual anyway
> > > IMHO.)
> > 
> > It seems that's not much of a danger -- the interactive 
> > Postgres documentation
> > hardly gets any comments at all in the first place. It would be a big
> > improvement if there were some way to encourage many more comments.
> 
> We can get from 2 - 10 a day I would guess. They get mailed to a closed
> list for moderation.
> 

It's not so much closed as just separate and this was mainly because the
folks on -docs and the folks on -www didn't want all the traffic.  

FWIW the PHP docs do actually integrate their comments into the docs,
although this seems to have slowed down much more over the recent years.
(I know they used to do it though, cause several comments I put in 5+
years ago have been integrated into the mainline docs).  

On the PostgreSQL front, Tom has in the past gone through comments
around release time and integrated in the relevant changes; I've also
submitted a patch or two based on suggestions that have come across
since we got the new system in place. If you're interested in moderating
the comments and have time to write patches for new suggestions I'm sure
most people would be happy to have you on board.


Robert Treat
-- 
Build A Brighter Lamp :: Linux Apache {middleware} PostgreSQL



Re: Interactive docs idea

From
Alvaro Herrera
Date:
On Thu, Apr 14, 2005 at 11:54:56AM -0400, Robert Treat wrote:

> On the PostgreSQL front, Tom has in the past gone through comments
> around release time and integrated in the relevant changes; I've also
> submitted a patch or two based on suggestions that have come across
> since we got the new system in place. If you're interested in moderating
> the comments and have time to write patches for new suggestions I'm sure
> most people would be happy to have you on board.

So what list is this?

-- 
Alvaro Herrera (<alvherre[@]dcc.uchile.cl>)
"Java is clearly an example of a money oriented programming"  (A. Stepanov)


Re: Interactive docs idea

From
Greg Stark
Date:
"Dave Page" <dpage@vale-housing.co.uk> writes:

> We can get from 2 - 10 a day I would guess. They get mailed to a closed
> list for moderation.

Uhm, then where are they?

The comments in the PHP docs, while they contain a lot of garbage also contain
a lot of helpful tips and warnings. There's hardly any in the Postgres docs.


I think the idea of moderating the comments is inherently flawed. You can
either have the deliberate, planned documentation without the comments, or you
can have the wild-west style comments system, but trying to have it both ways
is impossible. It just leads to the current situation where the comments are
moribund.

-- 
greg



Re: Interactive docs idea

From
Alvaro Herrera
Date:
On Thu, Apr 14, 2005 at 01:39:11PM -0400, Greg Stark wrote:

> I think the idea of moderating the comments is inherently flawed. You can
> either have the deliberate, planned documentation without the comments, or you
> can have the wild-west style comments system, but trying to have it both ways
> is impossible. It just leads to the current situation where the comments are
> moribund.

What do you mean, moribund?  What happens is that at each release Tom
gets the comments and integrate whatever of value into the main text
body.  The rest are deleted.

That's the way it should be IMHO.

-- 
Alvaro Herrera (<alvherre[@]dcc.uchile.cl>)
"I dream about dreams about dreams", sang the nightingale
under the pale moon (Sandman)


Re: Interactive docs idea

From
"Joshua D. Drake"
Date:
>The comments in the PHP docs, while they contain a lot of garbage also contain
>a lot of helpful tips and warnings. There's hardly any in the Postgres docs.
>
>
If it were I, we would start a wiki that was linked from the docs but
not have the docs
themselves have the comments.

>
>I think the idea of moderating the comments is inherently flawed.
>
If more people were intelligent and reasonable human beings you would be
correct.
I have seen the comments we get and a lot are complete garbage.

> You can
>either have the deliberate, planned documentation without the comments, or you
>can have the wild-west style comments system, but trying to have it both ways
>is impossible. It just leads to the current situation where the comments are
>moribund.
>
>
See my comment about a wiki :)

Also shouldn't this all be on pgsql-www?

Sincerely,

Joshua D. Drake




Re: Interactive docs idea

From
Greg Stark
Date:
Alvaro Herrera <alvherre@dcc.uchile.cl> writes:

> On Thu, Apr 14, 2005 at 01:39:11PM -0400, Greg Stark wrote:
> 
> > I think the idea of moderating the comments is inherently flawed. You can
> > either have the deliberate, planned documentation without the comments, or you
> > can have the wild-west style comments system, but trying to have it both ways
> > is impossible. It just leads to the current situation where the comments are
> > moribund.
> 
> What do you mean, moribund?  What happens is that at each release Tom
> gets the comments and integrate whatever of value into the main text
> body.  The rest are deleted.

So there's no comments saying "here's a useful function written using this
function" or "watch out for this common bug" or "if what you want to do is
this you might want to check out this other function" or any of the thousands
of similar comments in the PHP docs.

Instead you get one good example that's worthy of being included in the
documentation and nothing else.

There's also a problem that people are less likely to put comments in if they
don't see any existing comments.

-- 
greg



Re: Interactive docs idea

From
Alvaro Herrera
Date:
On Thu, Apr 14, 2005 at 03:01:10PM -0400, Greg Stark wrote:
> Alvaro Herrera <alvherre@dcc.uchile.cl> writes:
> 
> > On Thu, Apr 14, 2005 at 01:39:11PM -0400, Greg Stark wrote:
> > 
> > > I think the idea of moderating the comments is inherently flawed. You can
> > > either have the deliberate, planned documentation without the comments, or you
> > > can have the wild-west style comments system, but trying to have it both ways
> > > is impossible. It just leads to the current situation where the comments are
> > > moribund.
> > 
> > What do you mean, moribund?  What happens is that at each release Tom
> > gets the comments and integrate whatever of value into the main text
> > body.  The rest are deleted.
> 
> So there's no comments saying "here's a useful function written using this
> function" or "watch out for this common bug" or "if what you want to do is
> this you might want to check out this other function" or any of the thousands
> of similar comments in the PHP docs.

You are right, there aren't.  But to me that's not a bad thing.  I'd
find PHP's manual much better if the main text body really covered the
subject instead of only showing a couple of examples, and leaving part
of the matter to the comments  (Even to "editor's notes" in the
comments!)

> Instead you get one good example that's worthy of being included in the
> documentation and nothing else.
> 
> There's also a problem that people are less likely to put comments in if they
> don't see any existing comments.

I have agree with you on this last assertion.

-- 
Alvaro Herrera (<alvherre[@]dcc.uchile.cl>)
"Postgres is bloatware by design: it was built to housePhD theses." (Joey Hellerstein, SIGMOD annual conference 2002)


Re: Interactive docs idea

From
Greg Stark
Date:
Alvaro Herrera <alvherre@dcc.uchile.cl> writes:

> > So there's no comments saying "here's a useful function written using this
> > function" or "watch out for this common bug" or "if what you want to do is
> > this you might want to check out this other function" or any of the thousands
> > of similar comments in the PHP docs.
> 
> You are right, there aren't.  But to me that's not a bad thing.  I'd
> find PHP's manual much better if the main text body really covered the
> subject instead of only showing a couple of examples, and leaving part
> of the matter to the comments  (Even to "editor's notes" in the
> comments!)

I think this is a false dichotomy. Nobody's arguing that we should let the
main body of the documentation rot in favour of the comments. There's no
reason we can't have more comments and still have nicer authoritative
documentation than the PHP folks :)

I really see the comments serving a separate purpose from the main body. The
main body should be the manual -- an authoritative reference. The comments
should be more like this mailing list only organized.

How many times have you seen a question on pgsql-general and thought "gee that
would be answered if only the poster searched the archives"? Well the comments
on PHP serve basically as an organized repository of such previous discuss.
Instead of being in a single archive to search through they're attached
directly to the relevant piece of the documentation.

Certainly comments that amount to bug reports about the documentation can be
addressed by fixing the documentation (and the comment can then be removed).
Likewise comments that suggest additions can be moved into the main body of
the documentation.

-- 
greg



Re: Interactive docs idea

From
"Dave Page"
Date:

> -----Original Message-----
> From: gsstark@mit.edu [mailto:gsstark@mit.edu]
> Sent: 14 April 2005 18:39
> To: Dave Page
> Cc: Greg Stark; pgsql-hackers@postgresql.org
> Subject: Re: [HACKERS] Interactive docs idea
>
> "Dave Page" <dpage@vale-housing.co.uk> writes:
>
> > We can get from 2 - 10 a day I would guess. They get mailed
> to a closed
> > list for moderation.
>
> Uhm, then where are they?

On the docs. Don't forget, PHP a) probably has a lot more users than we do, b) only keep one version of the docs
online,whilst we have many and c) have been doing this a lot longer than us. 

> The comments in the PHP docs, while they contain a lot of
> garbage also contain
> a lot of helpful tips and warnings. There's hardly any in the
> Postgres docs.

See above. We do get useful comments as well as rubbish.

> I think the idea of moderating the comments is inherently
> flawed. You can
> either have the deliberate, planned documentation without the
> comments, or you
> can have the wild-west style comments system, but trying to
> have it both ways
> is impossible. It just leads to the current situation where
> the comments are
> moribund.

Here's a couple of example from my inbox this morning:


[pgsql-slavestothewww] Comment 2332 added to page functions-conditional.html of version 8.0
Author: <deleted>
----
Sou do Brasil e gostei do seu site.Prabéns!


[pgsql-slavestothewww] Comment 2333 added to page install-upgrading.html of version 7.4
Author: Shayne Hardesty <0nuty1qz6jv0p1w001@sneakemail.com>
----
If you use pg_dump on an older version (say 7.1.x, 7.2.x, or 7.3.x) you will get complains from psql about carriage
returnsmust be represented as literal \r.  The workaround for this is to use the -d argument with pg_dump to dump as
insertstatements, but that makes restore ungodly slow (prohibitively slow in my case).  In one data test I did the
restoretook 4 days - not workable for a production SQL environment. 

The solution I found was to put together a perl script to clean the output of "pg_dump <<dbname>> > <<file>>" to change
carriagereturns to \r.  I'm sharing my script here in hopes someone finds it useful. 

-- BEGIN clean-pgdump.pl --
#!/usr/bin/perl -w

use strict;

my $file = shift @ARGV || '';
die "no input file specified\n" unless $file;

open(FILE, $file) || die "cannot read file: $!\n";
while (<FILE>) {  s'\r\\\n'\\r'go;  s'\r'\\r'go;
  print;
}
close(FILE);

exit;
-- END clean-pgdump.pl --

Execute the script with ./clean-pgdump.pl <<file>> > <<newfile>>
Then run "psql -d template1 -f <<newfile>>" to import




I think it's clear we need to moderate what gets on there and what doesn't (the first comment basically says 'I'm from
Baziland I like this site'). 

Whilst I'm on the subject I will also point out that early versions of the the idocs were un-moderated and we still
findgarbage in there from time to time. If anyone sees any, please email webmaster or pgsql-www with the url so we can
cleanit up. 

Regards, Dave.


Re: Interactive docs idea

From
"Jim C. Nasby"
Date:
On Fri, Apr 15, 2005 at 08:42:45AM +0100, Dave Page wrote:
> [pgsql-slavestothewww] Comment 2333 added to page install-upgrading.html of version 7.4
> Author: Shayne Hardesty <0nuty1qz6jv0p1w001@sneakemail.com>
> ----
> If you use pg_dump on an older version (say 7.1.x, 7.2.x, or 7.3.x) you will get complains from psql about carriage
returnsmust be represented as literal \r.  The workaround for this is to use the -d argument with pg_dump to dump as
insertstatements, but that makes restore ungodly slow (prohibitively slow in my case).  In one data test I did the
restoretook 4 days - not workable for a production SQL environment.
 
> 
> The solution I found was to put together a perl script to clean the output of "pg_dump <<dbname>> > <<file>>" to
changecarriage returns to \r.  I'm sharing my script here in hopes someone finds it useful.
 
> 
> -- BEGIN clean-pgdump.pl --
> #!/usr/bin/perl -w
> 
> use strict;
> 
> my $file = shift @ARGV || '';
> die "no input file specified\n" unless $file;
> 
> open(FILE, $file) || die "cannot read file: $!\n";
> while (<FILE>) {
>    s'\r\\\n'\\r'go;
>    s'\r'\\r'go;
> 
>    print;
> }
> close(FILE);
> 
> exit;
> -- END clean-pgdump.pl --
> 
> Execute the script with ./clean-pgdump.pl <<file>> > <<newfile>>
> Then run "psql -d template1 -f <<newfile>>" to import

I think this comment is a good example of a problem with the current
system; this comment applies to both 7.4 and 8.0, but it's only in the
7.4 version. It's also long enough that it might not get into the
mainline docs (though I'm completely guessing there). It would be useful
if there was a way to have a comment cross versions.
-- 
Jim C. Nasby, Database Consultant               decibel@decibel.org 
Give your computer some brain candy! www.distributed.net Team #1828

Windows: "Where do you want to go today?"
Linux: "Where do you want to go tomorrow?"
FreeBSD: "Are you guys coming, or what?"