Re: readability changes to postgres.sgml

On 8/19/19 10:36 PM, Erik Rijkers wrote:
> On 2019-08-20 07:05, Michael Paquier wrote:
>> On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote:
>>> New version attached with spelling errors fixed.
>>
>> I have gone through this patch, and I have a hard time understanding
>> why these are improvements over the existing wording.  In what does
>> this make things better?
>
> It's pretty simple, it improves readability.  It does so mainly by
> removing unnecessary text.
>
> +1
>
Thanks for jumping in Erik. Michael, one of the cornerstones of good
writing is that you should only use exactly as many words as needed to
convey your point accurately. The more words, the more room for
interpretation, confusion and error from the readers side. It is easy
for us to look at the docs and say, "They are fine". We aren't reading
these docs as someone brand new to the project.

In short, the simpler we make our docs without sacrificing accuracy the
easier the docs will be to comprehend.

JD

--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****