On Fri, Dec 16, 2016 at 8:07 PM, Tom Lane <t...@sss.pgh.pa.us> wrote: > I'm still not seeing any value in putting this sort of info into > a documentation section that's distinct from the release notes. > We've used links to wiki pages in the past when the information > seemed to be in flux, and that's reasonable. But what's the point > of just linking to somewhere else in the same document?
If the explanation is just a few sentences long, I see no reason not to include it in the release notes. But if it's comparable in length to a moderately-long chapter then why would we not make it its own chapter? I think your argument boils down to "people probably don't need very much detail about this". But I think that's the wrong line of thinking. In my view, we ought to ship just about as much quality documentation as people are willing to write. Saying that we're going to reject good-quality documentation because we don't want to have too much of it is like saying we want to reject good-quality features because we don't want to have too many of them, or good-quality regression tests because we don't want to have too much code coverage, or good-quality bug fixes because we don't want to have too few bugs. It is of course true that all of these things can be done in a bad way or to excess: our documentation could be a terabyte! our features could be so numerous as to befuddle even expert users! our regression tests could run for a hundred hours on a supercomputer! we could fix so many basically-trivial bugs that our committers all fall sobbing to the floor with crippling repetitive strain injuries! But let's not FUD things that are basically positive. I think it's fantastic that Josh Berkus wants to write more documentation, and if 10 other people show up to do similar work, I'll buy them all a beer at the next conference we're at together. I almost wrote "I'll buy them all a bear" but that might be over the top. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
