In-Reply-To: <4301.1111974862@sss.pgh.pa.us>
References: <20050327212050.GP51784@decibel.org>
	<4301.1111974862@sss.pgh.pa.us>
Mime-Version: 1.0 (Apple Message framework v619.2)
Content-Type: text/plain; charset=WINDOWS-1252; format=flowed
Message-Id: <d0a31a949aa70c8a8a722aa74af22159@sitening.com>
Content-Transfer-Encoding: quoted-printable
Cc: "Jim C. Nasby" <decibel@decibel.org>, pgsql-docs@postgresql.org
From: Thomas F.O'Connell <tfo@sitening.com>
Subject: Re: Version information in docs 
Date: Mon, 28 Mar 2005 10:03:49 -0600
To: Tom Lane <tgl@sss.pgh.pa.us>

For comparison, the MySQL docs seem to stay monolithic, at least=20
online. As in, they don't provide a different version of the manual for=20=

3.23, 4.0, 4.1, 5.0, etc.

They have a single manual that seems to be pretty thorough about the=20
version in which various features came online.

I haven't concluded which style of documentation is more intuitive, but=20=

when I've had to use MySQL, it has been nice to be able to go to one=20
document and look to see whether something has been implemented and=20
also when it was implemented. I suppose the same thing could be=20
achieved if the manual itself were versioned rather than individual=20
features being versioned, but you do have to look through various=20
versions of the manual if you're tracking features in PostgreSQL. If=20
you were dealing with multiple versions, it could become tedious. I've=20=

dealt with many different versions of MySQL, and it is definitely handy=20=

to have a history in single pages for features. Granted, the feature=20
set and SQL compatibility for MySQL have been much more volatile than=20
for PostgreSQL in the past few years, so maybe it's more striking and=20
necessary for them.

-tfo

--
Thomas F. O'Connell
Co-Founder, Information Architect
Sitening, LLC

Strategic Open Source =97 Open Your i=99

http://www.sitening.com/
110 30th Avenue North, Suite 6
Nashville, TN 37203-6320
615-260-0005

On Mar 27, 2005, at 7:54 PM, Tom Lane wrote:

> "Jim C. Nasby" <decibel@decibel.org> writes:
>> ISTM it would be very useful if the docs specified what version a
>> feature that would break in older versions was implemented in. The
>> example that comes to mind is argument names in CREATE FUNCTION, =
which
>> was added in 8.0. The 8.0 docs =
(http://lnk.nu/postgresql.org/1y3.html)
>> mention the ability to name arguments, but it doesn't mention that =
the
>> feature was added in 8.0 and can not be used in prior versions. =
Anyone
>> who's trying to write code that will run on multiple versions of
>> PostgreSQL would want to know this.
>
> The release notes cover that; or you can compare the docs for the=20
> oldest
> and newest versions you want to work with.  I think it would be more
> confusing than helpful for the reference pages to try to cover all the
> changes from version to version.
>
> 			regards, tom lane=