Thread: Hey! 'lil help on Features?

From:
Josh Berkus
Date:

All,

For the 8.4 release we *must* have a page which describes most of the
8.4 features in plainer English than the release notes do.  I've started
writing out descriptions on the wiki page:

http://wiki.postgresql.org/wiki/WhatsNew84

... but with over 200 features, there's no way I can write them all up
myself.  Please dive in!

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

From:
Santiago Zarate
Date:

Here are my two cents:

on http://wiki.postgresql.org/wiki/WhatsNew84

"parallel pg_restore" is under performance, in the release draft appears
as " Parallel Restore"  under "administration"... i'm not sure if this
is for marketing pruposes :P or a mistake... (Not moved because of that
doubt)


"sql2008 window functions" is under " Other Developer Features " but
also somewhat explained at top...

"default values" for functions same case as above..


also, made small changes on the wiki (check revision comments)

gonna try halp a lil bit more... after work

Josh Berkus escribió:
> All,
>
> For the 8.4 release we *must* have a page which describes most of the
> 8.4 features in plainer English than the release notes do.  I've started
> writing out descriptions on the wiki page:
>
> http://wiki.postgresql.org/wiki/WhatsNew84
>
> ... but with over 200 features, there's no way I can write them all up
> myself.  Please dive in!
>

From:
Josh Berkus
Date:

On 6/5/09 5:25 PM, Santiago Zarate wrote:
> Here are my two cents:

No ... I mean get a wiki account and add/edit stuff yourself.

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

From:
Josh Berkus
Date:

Santiago,

> "parallel pg_restore" is under performance, in the release draft appears
> as " Parallel Restore" under "administration"... i'm not sure if this is
> for marketing pruposes :P or a mistake... (Not moved because of that doubt)

No, the list of bullet-points which is there has a lot of duplications.
  Please remove the duplicates.

> "sql2008 window functions" is under " Other Developer Features " but
> also somewhat explained at top...

Yeah, I want that under "SQL".

> "default values" for functions same case as above..

Same.

>
> also, made small changes on the wiki (check revision comments)
>
> gonna try halp a lil bit more... after work

Thanks for help!


--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

From:
Santiago Zarate
Date:

Done, made some changes and removed the duplicates...

others need better definintion... looking for info... but saved in case
someone wants to improve these (under SQL)

grouped few items taht i guess should go under procedures... but not
moved... since i'm unsure

Ill see what else i can do there...

Later~

Josh Berkus escribió:
> Santiago,
>
>> "parallel pg_restore" is under performance, in the release draft appears
>> as " Parallel Restore" under "administration"... i'm not sure if this is
>> for marketing pruposes :P or a mistake... (Not moved because of that
>> doubt)
>
> No, the list of bullet-points which is there has a lot of duplications.
>  Please remove the duplicates.
>
>> "sql2008 window functions" is under " Other Developer Features " but
>> also somewhat explained at top...
>
> Yeah, I want that under "SQL".
>
>> "default values" for functions same case as above..
>
> Same.
>
>>
>> also, made small changes on the wiki (check revision comments)
>>
>> gonna try halp a lil bit more... after work
>
> Thanks for help!
>
>

From:
Greg Stark
Date:

On Fri, Jun 5, 2009 at 11:45 PM, Josh Berkus<> wrote:
>
> For the 8.4 release we *must* have a page which describes most of the 8.4
> features in plainer English than the release notes do.

I'm a bit puzzled. Is there some reason the release notes should be in
less plain English?

--
greg
http://mit.edu/~gsstark/resume.pdf

From:
Josh Berkus
Date:

On 6/6/09 7:15 PM, Greg Stark wrote:
> On Fri, Jun 5, 2009 at 11:45 PM, Josh Berkus<>  wrote:
>> For the 8.4 release we *must* have a page which describes most of the 8.4
>> features in plainer English than the release notes do.
>
> I'm a bit puzzled. Is there some reason the release notes should be in
> less plain English?

Yes.  The release notes are in *technical* English, which may be
perfectly clear to you, but it's not to 99% of the world.  Actually, I'd
say that our release notes are only really comprehensible to people who
are already familiar with the PostgreSQL code.  Which is fine; they are
release notes.

However, we need a document which is understandible to non-programmers
who have never used PostgreSQL before.

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

From:
Josh Berkus
Date:

Santiago,

> grouped few items taht i guess should go under procedures... but not
> moved... since i'm unsure

Aha ... bit of clarification.  "Procedures" is for new features for
writing stored procedures, like the PL/pgSQL CASE statement and Default
parameters.  Per your note, I've *added* a new section, called "new
builtin functions" for all of the useful new little functions we have.


--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

From:
Josh Berkus
Date:

 > The release notes are in *technical* English, which may be
> perfectly clear to you, but it's not to 99% of the world. Actually, I'd
> say that our release notes are only really comprehensible to people who
> are already familiar with the PostgreSQL code. Which is fine; they are
> release notes.
>
> However, we need a document which is understandible to non-programmers
> who have never used PostgreSQL before.

Hmmm.  Now *I'm* not being clear.

The release notes are meant to have strong technical detail around what
specific changes have been made to Postgres.  This is necessary so that
our contributors and users who fiddle with PostgreSQL's guts (such as
the many people who maintain forks and tools) can know exactly what they
need to do to support the new release.

However, that kind of a document is not very useful for a reporter, a
blogger, an application developer, or a regular PostgreSQL user who is
evaluating PostgreSQL 8.4.  The descriptions of changes are technical
and hard to understand, and the organization and categories of the
release notes are more based on history than designed for easy browsing.
  Most of all, many of the descriptions in the release notes give no
clue what the feature is *for*.

Therefore, we need a second document designed to be easily understood by
the casual user or evaluator, which glosses over technical details.

This isn't new; we did it for 8.3:
http://www.postgresql.org/docs/8.3/static/release-8-3.html
http://www.postgresql.org/about/press/features83

This document is very important because, like 8.3, 8.4 has far too many
features to be listed in the main press kit.  And for many of our users,
they care more about one small fix than they do for the "major" features
of 8.4.

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

From:
Dimitri Fontaine
Date:

Hi,

Le 7 juin 09 à 21:04, Josh Berkus a écrit :
> Therefore, we need a second document designed to be easily
> understood by the casual user or evaluator, which glosses over
> technical details.

I just spent some time on it, having this in mind. You already knew
you had to proof-read my English, now you'll certainly have to adapt
the style, as it's uneasy for me to target a friendly non-technical
language while keeping it formal enough.

Hoping I didn't add work for you... regards,
--
dim

From:
Alvaro Herrera
Date:

Josh Berkus wrote:
> All,
>
> For the 8.4 release we *must* have a page which describes most of the
> 8.4 features in plainer English than the release notes do.  I've started
> writing out descriptions on the wiki page:
>
> http://wiki.postgresql.org/wiki/WhatsNew84

I'm reading this:

Auto-Tuning Free Space Map

    * Didn't you love that max_fsm_pages setting? Well, it's gone now. The Free Space Map now automatically sizes
itselfto the amount of free space you need to track (available memory permitting).  


I wanted to note that the FSM is now stored on disk, not memory, so
there's no reason to keep the "(available memory permitting)" caveat.
The new FSM is not "autotuning", it's simply complete.

--
Alvaro Herrera                                http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

From:
Gregory Stark
Date:

Josh Berkus <> writes:

> However, that kind of a document is not very useful for a reporter, a
> blogger,

ok.


> an application developer, or a regular PostgreSQL user who is evaluating
> PostgreSQL 8.4.

If it's not useful for an application developer evaluating 8.4 then I think
that's a problem. Do you have any specific problems we can address?

> The descriptions of changes are technical and hard to understand, and the
> organization and categories of the release notes are more based on history
> than designed for easy browsing. descriptions in the release notes give no
> clue what the feature is *for*.

These are all good suggestions but they seem like problems we should fix with
the release notes.


> Therefore, we need a second document designed to be easily understood by the
> casual user or evaluator, which glosses over technical details.
>
> This isn't new; we did it for 8.3:
> http://www.postgresql.org/docs/8.3/static/release-8-3.html
> http://www.postgresql.org/about/press/features83

I do like that document. But it seems like we should have the same structure
for the release notes and the same text, just with added details for each
item.

--
  Gregory Stark
  http://mit.edu/~gsstark/resume.pdf

From:
Josh Berkus
Date:

Greg,

> I do like that document. But it seems like we should have the same structure
> for the release notes and the same text, just with added details for each
> item.

Well, on a practical basis we can't do that for 8.4; the release notes
need to be finalized by Monday, and there's still a lot of work to be
done on the general public descriptions of features.

Might be worth talking about for 8.5 though.

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

From:
Santiago Zarate
Date:

hi guys...  another two cents... more about structure than writting...

moved:

*Support for statement level triggers for TRUNCATE command (procedures)

* Partial Match support for Full Text Search (SQL)
* Case Insensitive Text module (SQL)

and did also some minor editions on the doc... wiped out two sections
which where empty...

What's left? :P

Have fun...

Josh Berkus escribió:
> Greg,
>
>> I do like that document. But it seems like we should have the same
>> structure
>> for the release notes and the same text, just with added details for each
>> item.
>
> Well, on a practical basis we can't do that for 8.4; the release notes
> need to be finalized by Monday, and there's still a lot of work to be
> done on the general public descriptions of features.
>
> Might be worth talking about for 8.5 though.
>

From:
Josh Berkus
Date:

On 6/16/09 11:35 PM, Santiago Zarate wrote:
> hi guys...  another two cents... more about structure than writting...
>
> moved:
>
> *Support for statement level triggers for TRUNCATE command (procedures)
>
> * Partial Match support for Full Text Search (SQL)
> * Case Insensitive Text module (SQL)
>
> and did also some minor editions on the doc... wiped out two sections
> which where empty...
>
> What's left? :P

Someone needs to check this page against the release notes and see what
we missed.


--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

From:
Santiago Zarate
Date:

ill give it a look later...

Josh Berkus escribió:
> On 6/16/09 11:35 PM, Santiago Zarate wrote:
>> hi guys...  another two cents... more about structure than writting...
>>
>> moved:
>>
>> *Support for statement level triggers for TRUNCATE command (procedures)
>>
>> * Partial Match support for Full Text Search (SQL)
>> * Case Insensitive Text module (SQL)
>>
>> and did also some minor editions on the doc... wiped out two sections
>> which where empty...
>>
>> What's left? :P
>
> Someone needs to check this page against the release notes and see what
> we missed.
>
>