Skip site navigation (1) Skip section navigation (2)

Re: Version information in docs

From: Thomas F(dot)O'Connell <tfo(at)sitening(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: "Jim C(dot) Nasby" <decibel(at)decibel(dot)org>, pgsql-docs(at)postgresql(dot)org
Subject: Re: Version information in docs
Date: 2005-03-28 16:03:49
Message-ID: d0a31a949aa70c8a8a722aa74af22159@sitening.com (view raw or flat)
Thread:
Lists: pgsql-docs
For comparison, the MySQL docs seem to stay monolithic, at least 
online. As in, they don't provide a different version of the manual for 
3.23, 4.0, 4.1, 5.0, etc.

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

I haven't concluded which style of documentation is more intuitive, but 
when I've had to use MySQL, it has been nice to be able to go to one 
document and look to see whether something has been implemented and 
also when it was implemented. I suppose the same thing could be 
achieved if the manual itself were versioned rather than individual 
features being versioned, but you do have to look through various 
versions of the manual if you're tracking features in PostgreSQL. If 
you were dealing with multiple versions, it could become tedious. I've 
dealt with many different versions of MySQL, and it is definitely handy 
to have a history in single pages for features. Granted, the feature 
set and SQL compatibility for MySQL have been much more volatile than 
for PostgreSQL in the past few years, so maybe it's more striking and 
necessary for them.

-tfo

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

Strategic Open Source — Open Your i™

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(at)decibel(dot)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 
> 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

In response to

Responses

pgsql-docs by date

Next:From: David FetterDate: 2005-03-28 16:22:44
Subject: Re: Missing doc on expression format for ALTER TABLE
Previous:From: Josh BerkusDate: 2005-03-28 05:50:47
Subject: Re: Missing doc on expression format for ALTER TABLE

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group