Heikki Linnakangas <hlinnaka@iki.fi> writes:
> On 14/12/2020 21:50, Joshua Drake wrote:
>> Issues that are resolved with the optimized text:
>>
>> * Succinct text is more likely to be read than skimmed
>>
>> * Removal of extraneous mentions of PostgreSQL
>>
>> * Removal of unneeded justifications
>>
>> * Joining of two paragraphs into one that provides only the needed
>> information to the user
>>
>> * Word count decreased by over 50%. As changes such as these are
>> adopted it would make the documentation more consumable.
> I agree with these goals in general. I like to refer to
> http://www.plainenglish.co.uk/how-to-write-in-plain-english.html when
> writing documentation. Or anything else, really.
I think this particular chunk of text is an outlier. (Not unreasonably
so; as Heikki notes, it's customary for the very beginning of a book to
be a bit more formal.) Most of the docs contain pretty dense technical
material that's not going to be improved by making it even denser.
Also, to the extent that there's duplication, it's often deliberate.
For example, if a given bit of info appears in the tutorial and the
main docs and the reference pages, that doesn't mean we should rip
out two of the three appearances.
There certainly are sections that are crying out for reorganization,
but that's going to be very topic-specific and not something that
just going into it with a copy-editing mindset will help.
In short, the devil's in the details. Maybe there are lots of
places where this type of approach would help, but I think it's
going to be a case-by-case discussion not something where there's
a clear win overall.
regards, tom lane