Prev: Documentation patch: Re: postmap -q and ldap
Next: performance tuning - relay
From: /dev/rob0 on 24 Jun 2010 15:30
On Thu, Jun 24, 2010 at 09:39:05AM -0700, Quanah Gibson-Mount wrote:
> --On Wednesday, June 23, 2010 5:28 PM -0400 Victor Duchovni
> <Victor.Duchovni(a)morganstanley.com> wrote:
>
>> http://www.postfix.org/ldap_table.5.html
>>
>> BACKWARDS COMPATIBILITY
>> For backwards compatibility with Postfix version 2.0 and
>
> So you leave your online documentation using the syntax of a
> release that is 6 years old? That seems fairly odd. Why not use
> versioned documentation?
>
> Just as an example, OpenLDAP has:
>
> <http://www.openldap.org/doc/admin24/>
> <http://www.openldap.org/doc/admin23/>
> <http://www.openldap.org/doc/admin22/>
> <http://www.openldap.org/doc/admin21/>
> <http://www.openldap.org/doc/admin20/>
>
> This way people who want the official documentation for
> OpenLDAP 2.0 through 2.4 can get at those, even if they are
> no longer maintained.
>
> Same for the online manual pages, where you can pull them down
> for everything from OpenLDAP 1.0 onwards.
>
> In this way, people are able to get the information that is most
> relevant to their setup, and not get hit with examples that are
> half a decade out of date.

I generally recommend that people consult their own documentation in
their local $html_directory. This helps avoid the confusion which
comes with future features and syntax.

Note that versioned documentation for Postfix is always readily
available, even if not easily found via WWW. All you have to do is
get the source tarball for your Postfix release.

Simiarly it would be trivial for Wietse to put these online at
www.postfix.org under version directories like OpenLDAP's, but I'm
pretty sure he will not want to do this. The goal in Postfix is for
man pages and READMEs to be relevant for any version, except as may
be noted in the document, such as in MILTER_README and DSN_README
(those features were both added with Postfix 2.3)

Another drawback to having versioned documentation online is that El
Goog is as likely to find the wrong version of a document. If a
seeker ends up at http://www.postfix.org/documentation.html , all's
well, but not necessarily so if they find someone's old, non-updated
mirror.
--
Offlist mail to this address is discarded unless
"/dev/rob0" or "not-spam" is in Subject: header

From: Phil Howard on 24 Jun 2010 15:50
On Thu, Jun 24, 2010 at 15:30, /dev/rob0 <rob0(a)gmx.co.uk> wrote:

> Another drawback to having versioned documentation online is that El
> Goog is as likely to find the wrong version of a document. If a
> seeker ends up at http://www.postfix.org/documentation.html , all's
> well, but not necessarily so if they find someone's old, non-updated
> mirror.

Use the robots.txt file to tell Google to avoid the directory for
older documentation.

From: Wietse Venema on 24 Jun 2010 17:29
> > So you leave your online documentation using the syntax of a
> > release that is 6 years old? That seems fairly odd. Why not use
> > versioned documentation?

People can legitimately use Postfix over a span of many years.
Currently, the oldest supported release is Postfix version 2.4,
which was released in 2007. Currently, stable releases are supported
for four years.

With only one documentation version on-line, people with a question
will discover (via Google or otherwise) that their problem is
already solved in a later Postfix version. They can skip the effort
of posting a feature request, and consider upgrading to a newer
version that solves their problem.

Every feature documents its history, so that people won't be
disappointed when some feature does not work in their version of
Postfix.

Wietse

 | 
Pages: 1
Prev: Documentation patch: Re: postmap -q and ldap
Next: performance tuning - relay