Date: Fri, 8 May 2020 09:14:01 +0200 (CEST)
From: Fabien COELHO <coelho@cri.ensmp.fr>
To: Tom Lane <tgl@sss.pgh.pa.us>
cc: Bruce Momjian <bruce@momjian.us>,
    PostgreSQL-development <pgsql-hackers@postgresql.org>
Subject: Re: PG 13 release notes, first draft
In-Reply-To: <24479.1588859528@sss.pgh.pa.us>
Message-ID: <alpine.DEB.2.22.394.2005080840310.914063@pseudo>
References: <20200505031600.GB21752@momjian.us>
 <alpine.DEB.2.22.394.2005050710540.175044@pseudo>
 <20200505140055.GC21752@momjian.us>
 <alpine.DEB.2.22.394.2005051811320.2183756@pseudo>
 <20200506230750.GA3649@momjian.us>
 <alpine.DEB.2.22.394.2005070807160.211403@pseudo>
 <20200507130804.GG3649@momjian.us> <24479.1588859528@sss.pgh.pa.us>
User-Agent: Alpine 2.22 (DEB 394 2020-01-19)
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII; format=flowed
Precedence: bulk


Hello Tom,

>> Uh, can someone else give an opinion on this?  I am not sure how hard or
>> un-fun an item is should be used as criteria.

> Historically we don't document documentation changes at all, do we?

ISTM that the "we did not do it previously" is as weak an argument as 
un-fun-ness:-)

> It seems (a) pointless

I disagree, on the very principle of free software values as a social 
movement.

Documentation improvements should be encouraged, and recognizing these in 
the release notes contributes to do that for what is a lot of unpaid work 
given freely by many people. I do not see this as "pointless", on the 
contrary, having something "free" in a mostly mercantile world is odd 
enough to deserve some praise.

How many hours have you spent on the function operator table improvements? 
If someone else had contributed that and only that to a release, would it 
not justify two lines of implicit thanks somewhere down in the release 
notes?

Moreover adding a documentation section costs next to nothing, so what is 
the actual point of not doing it? Also, having some documentation 
improvements listed under "source code" does not make sense: writing good, 
precise and structured English is not "source code".

> and (b) circular.

Meh. The whole documentation is "circular" by construction, with 
references from one section to the next and back, indexes, glossary, 
acronyms, tutorials, whatever.

-- 
Fabien.