Re: Optimizing the documentation

On Mon, Dec 14, 2020 at 01:38:05PM -0800, Peter Geoghegan wrote:
> On Mon, Dec 14, 2020 at 12:50 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > Most of the docs contain pretty dense technical
> > material that's not going to be improved by making it even denser.
>
> It's always hard to write dense technical prose, for a variety of
> reasons. I often struggle with framing. For example I seem to write
> sentences that sound indecisive. But is that necessarily a bad thing?
> It seems wise to hedge a little bit when talking about (say) some kind
> of complex system with many moving parts. Ernest Hemingway never had
> to describe how VACUUM works.
>
> I agree with Heikki to some degree; there is value in trying to follow
> a style guide. But let's not forget about the other problem with the
> docs, which is that there isn't enough low level technical details of
> the kind that advanced users value. There is a clear unmet demand for
> that IME. If we're going to push in the direction of simplification,
> it should not make this other important task harder.

I agree a holistic review of the docs can yield great benefits. No one
usually complains about overly verbose text, but making it clearer is
always a win. Anyway, of course, it is going to be very specific for
each case. As an extreme example, in 2007 when I did a full review of
the docs, I clarified may/can/might in our docs, and it probably helped.
Here is one of several commits:

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=e81c138e18

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EnterpriseDB https://enterprisedb.com

The usefulness of a cup is in its emptiness, Bruce Lee