On Thu, Dec 15, 2016 at 1:11 AM, Bruce Momjian <bruce@momjian.us> wrote:
On Wed, Dec 14, 2016 at 02:29:07PM -0800, Josh Berkus wrote: > On 12/14/2016 08:06 AM, Bruce Momjian wrote: > > On Fri, Dec 9, 2016 at 09:46:44AM +0900, Michael Paquier wrote: > >>>> My own take on it is that the release notes are already a massive > >>>> amount of work, and putting duplicative material in a bunch of other > >>>> places isn't going to make things better, it'll just increase the > >>>> maintenance burden. > >>> > >>> This would mean adding literally pages of material to the release notes. > >>> In the past, folks have been very negative on anything which would make > >>> the release notes longer. Are you sure? > >> > >> As that's a per-version information, that seems adapted to me. There > >> could be as well in the release notes a link to the portion of the > >> docs holding this manual. Definitely this should be self-contained in > >> the docs, and not mention the wiki. My 2c. > > > > Yes, that is the usual approach. > > > > So where in the docs should these go, then? We don't (currently) have a > place for this kind of doc. Appendices?
You are saying this is more massive than any other change we have made in the past? In general, what need to be documented?
I don't necessarily think it's because it's more massive than any chance we have made before. I think it's more that this is something that we probably should've had before, and just didn't.
Right now we basically have a bulletpoint list of things that are new, with a section about things that are incompatible. Having an actual section with more detailed descriptions of how to handle these changes would definitely be a win. it shouldn't *just* be for these changes of course, it should be for any other changes that are large enough to benefit from more than a oneliner about the fact that they've changed.
